Greptimedb

🚀 greptimedb-mcp-server

A Model Context Protocol (MCP) server implemented for GreptimeDB. This server provides a secure and structured interface for AI assistants to explore and analyze the database. It allows assistants to list tables, read data, and execute SQL queries through a controlled interface, enabling responsible database access.

🚀 Quick Start

The greptimedb-mcp-server offers a structured way for AI assistants to interact with GreptimeDB. It provides a set of functions to manage database resources and execute SQL queries.

✨ Features

• list_resources: List tables.
• read_resource: Read table data.
• list_tools: List available tools.
• call_tool: Execute SQL queries.
• list_prompts: List available prompts.
• get_prompt: Retrieve a prompt by its name.

📦 Installation

You can install the greptimedb-mcp-server using pip:

pip install greptimedb-mcp-server

📚 Documentation

Configuration

You can configure the server by setting environment variables or using command-line arguments.

Environment Variables

GREPTIMEDB_HOST=localhost    # Database host
GREPTIMEDB_PORT=4002         # Optional: Database port (default is 4002 if not specified)
GREPTIMEDB_USER=root
GREPTIMEDB_PASSWORD=
GREPTIMEDB_DATABASE=public

Command-line Arguments

• --host: Database host.
• --port: Database port.
• --user: Database username.
• --password: Database password.
• --database: Database name.

Usage

Integration with Claude Desktop

Configure the MCP server in the Claude Desktop 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

This project is licensed under the MIT License - see the LICENSE.md file for details.

🔧 Technical Details

Contribution

Prerequisites

• Python with the uv package manager.
• GreptimeDB installed.
• Dependencies for the MCP server.

Development

# 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 development dependencies
uv sync

# Run tests
pytest

You can use the MCP Inspector for debugging:

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

Acknowledgments

We would like to express our gratitude to the following repositories for their code contributions:

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