GreptimeDB Meets AI: Unleashing Database Insights with the Model Context Protocol (MCP) Server

This document details the greptimedb-mcp-server, a crucial component for integrating GreptimeDB, a time-series database, with Large Language Model (LLM) applications via the Model Context Protocol (MCP). This integration empowers AI assistants to securely and intelligently interact with your database, enabling powerful data exploration and analysis capabilities.

Core Functionality: Bridging the Gap Between LLMs and GreptimeDB

The greptimedb-mcp-server acts as a translator, allowing LLMs to understand and interact with GreptimeDB. It exposes a set of standardized MCP capabilities, including:

list_resources: Discovers available tables within the GreptimeDB instance, providing the LLM with a map of the data landscape.
read_resource: Retrieves data from specified tables, enabling the LLM to access the raw information needed for analysis and reasoning.
list_tools: Enumerates available tools, in this case, the ability to execute SQL queries. This allows the LLM to leverage the power of SQL for complex data manipulation.
call_tool: Executes SQL queries against the GreptimeDB instance, providing a mechanism for the LLM to perform sophisticated data analysis and extraction. This is the workhorse of the integration, allowing the LLM to ask complex questions of the data.
list_prompts: Lists available prompt templates, enabling the LLM to use pre-defined queries or instructions for specific tasks.
get_prompt: Retrieves a specific prompt template by name, allowing for the reuse of common queries and analysis patterns.

Installation and Configuration: Getting Started

Prerequisites

A running GreptimeDB instance.
Python 3.7+ with pip package manager.

Installation Steps

Install the greptimedb-mcp-server using pip:

pip install greptimedb-mcp-server

Configuration

The server requires connection details for your GreptimeDB instance. These can be configured via environment variables or command-line arguments.

Environment Variables (Recommended for Production)

Set the following environment variables to match your GreptimeDB configuration:

GREPTIMEDB_HOST=your_greptimedb_host  # e.g., localhost
GREPTIMEDB_PORT=4002                   # Optional: Defaults to 4002
GREPTIMEDB_USER=your_username          # e.g., root
GREPTIMEDB_PASSWORD=your_password      # Leave blank if no password
GREPTIMEDB_DATABASE=your_database_name  # e.g., public

Command-Line Arguments (For Development and Testing)

Alternatively, you can specify the connection details as command-line arguments:

python -m greptimedb_mcp_server.server --host your_greptimedb_host --port 4002 --user your_username --password your_password --database your_database_name

Integration with Claude Desktop (Example)

This section demonstrates how to integrate the greptimedb-mcp-server with Claude Desktop, a popular LLM application.

Locate the Claude Desktop Configuration File:
- MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json

Modify the Configuration File:

Add a new entry under the "mcpServers" section to configure the greptimedb-mcp-server. Adjust the "command", "args", and "env" values to match your environment.

{
  "mcpServers": {
    "greptimedb": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/greptimedb-mcp-server",
        "run",
        "-m",
        "greptimedb_mcp_server.server"
      ],
      "env": {
        "GREPTIMEDB_HOST": "localhost",
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "root",
        "GREPTIMEDB_PASSWORD": "",
        "GREPTIMEDB_DATABASE": "public"
      }
    }
  }
}

command: The command to execute the server. uv is a fast Python package installer and runner.
args: Arguments passed to the command. This example assumes the server is run using uv. Adjust the path to the greptimedb-mcp-server directory accordingly.
env: Environment variables passed to the server. This is where you configure the GreptimeDB connection details.

Restart Claude Desktop: The changes will take effect after restarting the application.

Development and Contribution: Building a Better Integration

Prerequisites

Python with uv package manager.
A running GreptimeDB instance.
Familiarity with the Model Context Protocol.

Development Setup

Clone the Repository:

git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server

Create a Virtual Environment:

uv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

Install Dependencies:
```
uv sync
```
Run Tests:
```
pytest
```

Debugging with MCP Inspector

The MCP Inspector is a valuable tool for debugging MCP server implementations. Use the following command to run the server with the inspector:

npx @modelcontextprotocol/inspector uv \
  --directory \
  /path/to/greptimedb-mcp-server \
  run \
  -m \
  greptimedb_mcp_server.server

Acknowledgements

This library builds upon the work of others in the MCP community. We extend our gratitude to the authors of the following repositories, whose code has inspired and informed this implementation:

Their contributions have been invaluable in the development of this project.