GreptimeDB MCP Server

What is GreptimeDB MCP Server about?

GreptimeDB MCP Server implements a Model Context Protocol (MCP) server that allows AI assistants to interact with a GreptimeDB instance in a safe, query‑driven manner. It abstracts database operations into MCP calls such as list_resources, read_resource, and call_tool.

How to use GreptimeDB MCP Server?

1. Installation

   pip install greptimedb-mcp-server
   

2. Configuration – set environment variables or pass command‑line arguments:

   export GREPTIMEDB_HOST=localhost
   export GREPTIMEDB_PORT=4002   # optional, defaults to 4002
   export GREPTIMEDB_USER=root
   export GREPTIMEDB_PASSWORD=
   export GREPTIMEDB_DATABASE=public
   export GREPTIMEDB_TIMEZONE=UTC
   

   Alternatively, start the server with CLI options --host, --port, --user, --password, --database, and --timezone.
3. Running the server (example using uv):

   uv run -m greptimedb_mcp_server.server
   

4. Integrate with AI tools – e.g., Claude Desktop can invoke the server via the MCP configuration described in the README.

Key Features of GreptimeDB MCP Server

• Resource listing – list_resources returns available tables.
• Data reading – read_resource fetches rows from a specified table.
• SQL execution – call_tool runs arbitrary SQL statements in a controlled context.
• Prompt management – list_prompts and get_prompt expose reusable prompts for AI assistants.
• Tool discovery – list_tools enumerates callable operations.
• Environment‑driven configuration – easy setup via env vars or CLI flags.
• Experimental status – clearly marked as a prototype, encouraging cautious use.

Use Cases of GreptimeDB MCP Server

• AI‑assisted data exploration – let LLMs query time‑series data without exposing raw credentials.
• Chatbot integration – embed database querying capabilities in conversational agents.
• Rapid prototyping – developers can test AI‑driven analytics pipelines against GreptimeDB.
• Secure sandbox – restrict database access to predefined MCP calls, reducing risk of arbitrary query injection.

FAQ from the GreptimeDB MCP Server

• Q: Is the server production‑ready? A: It is experimental; data security and privacy considerations are not fully addressed yet.
• Q: Which database ports are supported? A: The server expects the MySQL protocol port of GreptimeDB (default 4002).
• Q: How do I change the time zone for queries? A: Set GREPTIMEDB_TIMEZONE or use the --timezone CLI flag.
• Q: Can I run the server inside a container? A: Yes, install the package inside the container and expose the MCP endpoint as you would any Python service.
• Q: What Python version is required? A: The project follows standard Python 3 compatibility; using the uv package manager ensures correct environment setup.

greptimedb-mcp-server

A Model Context Protocol (MCP) server implementation for GreptimeDB.

This server provides AI assistants with a secure and structured way to explore and analyze databases. It enables them to list tables, read data, and execute SQL queries through a controlled interface, ensuring responsible database access.

Project Status

This is an experimental project that is still under development. Data security and privacy issues have not been specifically addressed, so please use it with caution.

Capabilities

• list_resources to list tables
• read_resource to read table data
• list_tools to list tools
• call_tool to execute an SQL
• list_prompts to list prompts
• get_prompt to get the prompt by name

Installation

pip install greptimedb-mcp-server

Configuration

Set the following environment variables:

GREPTIMEDB_HOST=localhost    # Database host
GREPTIMEDB_PORT=4002         # Optional: Database MySQL port (defaults to 4002 if not specified)
GREPTIMEDB_USER=root
GREPTIMEDB_PASSWORD=
GREPTIMEDB_DATABASE=public
GREPTIMEDB_TIMEZONE=UTC

Or via command-line args:

• --host the database host, localhost by default,
• --port the database port, must be MySQL protocol port, 4002 by default,
• --user the database username, empty by default,
• --password the database password, empty by default,
• --database the database name, public by default.
• --timezone the session time zone, empty by default(using server default time zone).

Usage

Claude Desktop Integration

Configure the MCP server in Claude Desktop's configuration file:

MacOS

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

Location: %APPDATA%/Claude/claude_desktop_config.json

{
  "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",
        "GREPTIMEDB_TIMEZONE": ""
      }
    }
  }
}

License

MIT License - see LICENSE.md file for details.

Contribute

Prerequisites

• Python with uv package manager
• GreptimeDB installation
• MCP server dependencies

Development

# Clone the repository
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server

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

# Install development dependencies
uv sync

# Run tests
pytest

Use MCP Inspector for debugging:

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

Acknowledgement

This library's implementation was inspired by the following two repositories and incorporates their code, for which we express our gratitude：

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates

Thanks!