GitHub - GreptimeTeam/greptimedb-mcp-server: A Model Context Protocol (MCP) server for GreptimeDB (original) (raw)
greptimedb-mcp-server
A Model Context Protocol (MCP) server for GreptimeDB — an open-source, cloud-native, unified observability database.
Enables AI assistants to query and analyze GreptimeDB using SQL, TQL (PromQL-compatible), and RANGE queries, with built-in security features like read-only enforcement and data masking.
Quick Start
Install
pip install greptimedb-mcp-server
Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public
For Claude Desktop, add this to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{ "mcpServers": { "greptimedb": { "command": "greptimedb-mcp-server", "args": ["--host", "localhost", "--database", "public"] } } }
Features
Tools
| Tool | Description |
|---|---|
| execute_sql | Execute SQL queries with format (csv/json/markdown) and limit options |
| execute_tql | Execute TQL (PromQL-compatible) queries for time-series analysis |
| query_range | Execute time-window aggregation queries with RANGE/ALIGN syntax |
| describe_table | Get table schema including column names, types, and constraints |
| explain_query | Analyze SQL or TQL query execution plans |
| health_check | Check database connection status and server version |
Pipeline Management
| Tool | Description |
|---|---|
| list_pipelines | List all pipelines or get details of a specific pipeline |
| create_pipeline | Create a new pipeline with YAML configuration |
| dryrun_pipeline | Test a pipeline with sample data without writing to database |
| delete_pipeline | Delete a specific version of a pipeline |
Resources & Prompts
- Resources: Browse tables via
greptime://<table>/dataURIs - Prompts: Built-in templates for common tasks —
pipeline_creator,log_pipeline,metrics_analysis,promql_analysis,iot_monitoring,trace_analysis,table_operation
For LLM integration and prompt usage, see docs/llm-instructions.md.
Configuration
Environment Variables
GREPTIMEDB_HOST=localhost # Database host GREPTIMEDB_PORT=4002 # MySQL protocol port (default: 4002) GREPTIMEDB_USER=root # Database user GREPTIMEDB_PASSWORD= # Database password GREPTIMEDB_DATABASE=public # Database name GREPTIMEDB_TIMEZONE=UTC # Session timezone
Optional
GREPTIMEDB_HTTP_PORT=4000 # HTTP API port for pipeline management GREPTIMEDB_HTTP_PROTOCOL=http # HTTP protocol (http/https) GREPTIMEDB_POOL_SIZE=5 # Connection pool size GREPTIMEDB_MASK_ENABLED=true # Enable sensitive data masking GREPTIMEDB_MASK_PATTERNS= # Additional patterns (comma-separated) GREPTIMEDB_AUDIT_ENABLED=true # Enable audit logging
Transport (for HTTP server mode)
GREPTIMEDB_TRANSPORT=stdio # stdio, sse, or streamable-http GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host GREPTIMEDB_LISTEN_PORT=8080 # HTTP server bind port
CLI Arguments
greptimedb-mcp-server
--host localhost
--port 4002
--database public
--user root
--password ""
--timezone UTC
--pool-size 5
--mask-enabled true
--transport stdio
HTTP Server Mode
For containerized or Kubernetes deployments. Requires mcp>=1.8.0:
Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080
SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000
Security
Read-Only Database User (Recommended)
Create a read-only user in GreptimeDB using static user provider:
mcp_readonly:readonly=your_secure_password
Application-Level Security Gate
All queries go through a security gate that:
- Blocks: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
- Blocks: Encoded bypass attempts (hex, UNHEX, CHAR)
- Allows: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION
Data Masking
Sensitive columns are automatically masked (******) based on column name patterns:
- Authentication:
password,secret,token,api_key,credential - Financial:
credit_card,cvv,bank_account - Personal:
ssn,id_card,passport
Configure with --mask-patterns phone,email to add custom patterns.
Audit Logging
All tool invocations are logged:
2025-12-10 10:30:45 - greptimedb_mcp_server.audit - INFO - [AUDIT] execute_sql | query="SELECT * FROM cpu LIMIT 10" | success=True | duration_ms=45.2
Disable with --audit-enabled false.
Development
Clone and setup
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git cd greptimedb-mcp-server uv venv && source .venv/bin/activate uv sync
Run tests
pytest
Format & lint
uv run black . uv run flake8 src
Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server
License
MIT License - see LICENSE.md.
Acknowledgement
Inspired by: