Greptimedb MCP Server

1# greptimedb-mcp-server
2 
3[![PyPI - Version](https://img.shields.io/pypi/v/greptimedb-mcp-server)](https://pypi.org/project/greptimedb-mcp-server/)
4![build workflow](https://github.com/GreptimeTeam/greptimedb-mcp-server/actions/workflows/python-app.yml/badge.svg)
5[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
6 
7A Model Context Protocol (MCP) server for [GreptimeDB](https://github.com/GreptimeTeam/greptimedb) — an open-source, cloud-native, unified observability database.
8 
9Enables 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.
10 
11## Quick Start
12 
13```bash
14# Install
15pip install greptimedb-mcp-server
16 
17# Run (connects to localhost:4002 by default)
18greptimedb-mcp-server --host localhost --database public
19```
20 
21For Claude Desktop, add this to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
22 
23```json
24{
25  "mcpServers": {
26    "greptimedb": {
27      "command": "greptimedb-mcp-server",
28      "args": ["--host", "localhost", "--database", "public"]
29    }
30  }
31}
32```
33 
34## Features
35 
36### Tools
37 
38| Tool | Description |
39|------|-------------|
40| `execute_sql` | Execute SQL queries with format (csv/json/markdown) and limit options |
41| `execute_tql` | Execute TQL (PromQL-compatible) queries for time-series analysis |
42| `query_range` | Execute time-window aggregation queries with RANGE/ALIGN syntax |
43| `describe_table` | Get table schema including column names, types, and constraints |
44| `explain_query` | Analyze SQL or TQL query execution plans |
45| `health_check` | Check database connection status and server version |
46 
47### Pipeline Management
48 
49| Tool | Description |
50|------|-------------|
51| `list_pipelines` | List all pipelines or get details of a specific pipeline |
52| `create_pipeline` | Create a new pipeline with YAML configuration |
53| `dryrun_pipeline` | Test a pipeline with sample data without writing to database |
54| `delete_pipeline` | Delete a specific version of a pipeline |
55 
56### Resources & Prompts
57 
58- **Resources**: Browse tables via `greptime://<table>/data` URIs
59- **Prompts**: Built-in templates for common tasks — `pipeline_creator`, `log_pipeline`, `metrics_analysis`, `promql_analysis`, `iot_monitoring`, `trace_analysis`, `table_operation`
60 
61For LLM integration and prompt usage, see [docs/llm-instructions.md](docs/llm-instructions.md).
62 
63## Configuration
64 
65### Environment Variables
66 
67```bash
68GREPTIMEDB_HOST=localhost      # Database host
69GREPTIMEDB_PORT=4002           # MySQL protocol port (default: 4002)
70GREPTIMEDB_USER=root           # Database user
71GREPTIMEDB_PASSWORD=           # Database password
72GREPTIMEDB_DATABASE=public     # Database name
73GREPTIMEDB_TIMEZONE=UTC        # Session timezone
74 
75# Optional
76GREPTIMEDB_HTTP_PORT=4000      # HTTP API port for pipeline management
77GREPTIMEDB_HTTP_PROTOCOL=http  # HTTP protocol (http/https)
78GREPTIMEDB_POOL_SIZE=5         # Connection pool size
79GREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking
80GREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)
81GREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging
82 
83# Transport (for HTTP server mode)
84GREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http
85GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host
86GREPTIMEDB_LISTEN_PORT=8080    # HTTP server bind port
87GREPTIMEDB_ALLOWED_HOSTS=      # DNS rebinding protection (comma-separated)
88GREPTIMEDB_ALLOWED_ORIGINS=    # CORS allowed origins (comma-separated)
89```
90 
91### CLI Arguments
92 
93```bash
94greptimedb-mcp-server \
95  --host localhost \
96  --port 4002 \
97  --database public \
98  --user root \
99  --password "" \
100  --timezone UTC \
101  --pool-size 5 \
102  --mask-enabled true \
103  --transport stdio
104```
105 
106### HTTP Server Mode
107 
108For containerized or Kubernetes deployments. Requires `mcp>=1.8.0`:
109 
110```bash
111# Streamable HTTP (recommended for production)
112greptimedb-mcp-server --transport streamable-http --listen-port 8080
113 
114# SSE mode (legacy)
115greptimedb-mcp-server --transport sse --listen-port 3000
116```
117 
118#### DNS Rebinding Protection
119 
120By default, DNS rebinding protection is **disabled** for compatibility with proxies, gateways, and Kubernetes services. To enable it, use `--allowed-hosts`:
121 
122```bash
123# Enable DNS rebinding protection with allowed hosts
124greptimedb-mcp-server --transport streamable-http \
125  --allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*"
126 
127# With custom allowed origins for CORS
128greptimedb-mcp-server --transport streamable-http \
129  --allowed-hosts "my-service.namespace:*" \
130  --allowed-origins "http://localhost:*,https://my-app.example.com"
131 
132# Or via environment variables
133GREPTIMEDB_ALLOWED_HOSTS="localhost:*,my-service.namespace:*" \
134GREPTIMEDB_ALLOWED_ORIGINS="http://localhost:*" \
135  greptimedb-mcp-server --transport streamable-http
136```
137 
138If you encounter `421 Invalid Host Header` errors, either disable protection (default) or add your host to the allowed list.
139 
140## Security
141 
142### Read-Only Database User (Recommended)
143 
144Create a read-only user in GreptimeDB using [static user provider](https://docs.greptime.com/user-guide/deployments-administration/authentication/static/#permission-modes):
145 
146```
147mcp_readonly:readonly=your_secure_password
148```
149 
150### Application-Level Security Gate
151 
152All queries go through a security gate that:
153- **Blocks**: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
154- **Blocks**: Encoded bypass attempts (hex, UNHEX, CHAR)
155- **Allows**: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION
156 
157### Data Masking
158 
159Sensitive columns are automatically masked (`******`) based on column name patterns:
160- Authentication: `password`, `secret`, `token`, `api_key`, `credential`
161- Financial: `credit_card`, `cvv`, `bank_account`
162- Personal: `ssn`, `id_card`, `passport`
163 
164Configure with `--mask-patterns phone,email` to add custom patterns.
165 
166### Audit Logging
167 
168All tool invocations are logged:
169 
170```
1712025-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
172```
173 
174Disable with `--audit-enabled false`.
175 
176## Development
177 
178```bash
179# Clone and setup
180git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
181cd greptimedb-mcp-server
182uv venv && source .venv/bin/activate
183uv sync
184 
185# Run tests
186pytest
187 
188# Format & lint
189uv run black .
190uv run flake8 src
191 
192# Debug with MCP Inspector
193npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server
194```
195 
196## License
197 
198MIT License - see [LICENSE.md](LICENSE.md).
199 
200## Acknowledgement
201 
202Inspired by:
203- [ktanaka101/mcp-server-duckdb](https://github.com/ktanaka101/mcp-server-duckdb)
204- [designcomputer/mysql_mcp_server](https://github.com/designcomputer/mysql_mcp_server)
205- [mikeskarl/mcp-prompt-templates](https://github.com/mikeskarl/mcp-prompt-templates)
206