What is GreptimeDB MCP Server

greptimedb-mcp-server is an implementation of the Model Context Protocol (MCP) server designed for GreptimeDB. It facilitates AI assistants in securely exploring and analyzing databases, allowing for controlled access to database functionalities like listing tables, reading data, and executing SQL queries.

Use cases

This server can be employed in various scenarios where AI requires structured access to databases, such as data analysis, reporting, and automated querying. It serves as a bridge between AI assistants and databases, ensuring responsible and secure data management.

How to use

To use greptimedb-mcp-server, install it via pip. Configure the server by setting the necessary environment variables for database connection or using command-line arguments. Integrate it with Claude Desktop by modifying the configuration file to specify the MCP server details and environment settings.

Key features

Key features of greptimedb-mcp-server include the ability to list database resources, read table data, and execute SQL commands through a controlled interface. It also supports resource and prompt management, making it easier to interact with the database.

Where to use

The server is ideal for applications where AI needs to interact with databases in a secure and structured manner. It can be used in data-driven applications, AI research environments, or any setting that requires an efficient interface between AI systems and database management.

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!