GreptimeDB MCP Server

What is GreptimeDB MCP Server about?

A Model Context Protocol (MCP) server implementation that enables AI assistants to interact with GreptimeDB in a controlled manner. It exposes operations for listing tables, reading table data, executing arbitrary SQL statements, and managing prompts.

How to use GreptimeDB MCP Server?

1. Install

   pip install greptimedb-mcp-server
   

2. Configure – set connection parameters via environment variables or command‑line arguments:

   export GREPTIMEDB_HOST=localhost
   export GREPTIMEDB_PORT=4002
   export GREPTIMEDB_USER=root
   export GREPTIMEDB_PASSWORD=
   export GREPTIMEDB_DATABASE=public
   export GREPTIMEDB_TIMEZONE=UTC
   

   Or run the server with flags such as --host, --port, --user, --password, --database, --timezone.
3. Run the server (example for Claude Desktop integration):

   uv run -m greptimedb_mcp_server.server
   

   The server can also be started with a specific working directory using the --directory option.
4. Integrate – add the MCP server definition to the client configuration (e.g., Claude Desktop) pointing to the command and environment variables.

Key Features

• list_resources: retrieve a list of tables in the database.
• read_resource: fetch rows from a specified table with optional limits.
• list_tools: enumerate available tools (e.g., SQL executor).
• call_tool: run an arbitrary SQL query and return results.
• list_prompts / get_prompt: manage prompt templates for AI assistants.
• Simple installation via pip and flexible configuration through env vars or CLI.

Use Cases

• AI‑driven data exploration: Let chat‑based assistants query GreptimeDB without exposing raw credentials.
• Chatbot integration: Embed database lookup capabilities into conversational agents.
• Prototyping analytics tools: Quickly build front‑ends that rely on natural‑language queries.
• Testing and debugging: Use the MCP Inspector tool to inspect server behavior during development.

FAQ

Q: Is the server production‑ready? A: It is experimental; data security and privacy concerns have not been fully addressed, so use with caution.

Q: Which database versions are supported? A: GreptimeDB exposing a MySQL‑compatible protocol (default port 4002).

Q: How can I secure the server? A: Run it in a trusted environment, limit network exposure, and consider adding authentication layers on top of the MCP interface.

Q: Can I customize prompts? A: Yes, use the list_prompts and get_prompt endpoints to retrieve and manage prompt templates.

Q: How do I debug the server? A: The project recommends the MCP Inspector (npx @modelcontextprotocol/inspector uv …) for interactive debugging.

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!