greptimedb-mcp-server

PyPI - Version build workflow MIT License

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

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.

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" } } } }

License

MIT License - see LICENSE.md file for details.

Contribute

Related MCP server: MCP Toolkit

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