{
  "markdown": "# greptimedb-mcp-server\n\n[![PyPI - Version](https://img.shields.io/pypi/v/greptimedb-mcp-server)](https://pypi.org/project/greptimedb-mcp-server/)\n![build workflow](https://github.com/GreptimeTeam/greptimedb-mcp-server/actions/workflows/python-app.yml/badge.svg)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/?q=io.github.GreptimeTeam%2Fgreptimedb-mcp-server)\n[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)\n\nA Model Context Protocol (MCP) server for [GreptimeDB](https://github.com/GreptimeTeam/greptimedb) — an open-source observability database that handles metrics, logs, and traces in one engine.\n\n<!-- mcp-name: io.github.GreptimeTeam/greptimedb-mcp-server -->\n\nEnables 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.\n\n## Quick Start\n\n```bash\n# Install\npip install greptimedb-mcp-server\n\n# Run (connects to localhost:4002 by default)\ngreptimedb-mcp-server --host localhost --database public\n```\n\nFor Claude Desktop, add this to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"greptimedb\": {\n      \"command\": \"greptimedb-mcp-server\",\n      \"args\": [\"--host\", \"localhost\", \"--database\", \"public\"]\n    }\n  }\n}\n```\n\n## Features\n\n### Tools\n\n| Tool | Description |\n|------|-------------|\n| `execute_sql` | Execute SQL queries with format (csv/json/markdown) and limit options |\n| `execute_tql` | Execute TQL (PromQL-compatible) queries for time-series analysis |\n| `query_range` | Execute time-window aggregation queries with RANGE/ALIGN syntax |\n| `search_table_semantics` | Find tables by observability concept, ranked by matched terms; searches table names, semantic options, and entity declarations |\n| `describe_table` | Inspect a table profile: schema, semantic metadata, latest sample rows, and query guidance |\n| `explain_query` | Analyze SQL or TQL query execution plans (`analyze=true` for runtime stats; add `verbose=true` alongside `analyze=true` for per-partition scan metrics and index-pruning counters) |\n| `health_check` | Check database connection status and server version |\n\n`search_table_semantics` and the semantic metadata in `describe_table` read `information_schema.table_semantics`. A table appears there when it carries a `greptime.semantic.*` option or a built-in convention derives an entity declaration for it; other tables are absent. The server reads the view's column list once per process and selects only the columns it exposes. `entity_declarations` requires GreptimeDB 1.3; on earlier versions it is reported as a missing column rather than as an empty declaration set.\n\n### Pipeline Management\n\n| Tool | Description |\n|------|-------------|\n| `list_pipelines` | List all pipelines or get details of a specific pipeline |\n| `create_pipeline` | Create a new pipeline with YAML configuration |\n| `dryrun_pipeline` | Test a pipeline with sample data without writing to database |\n| `delete_pipeline` | Delete a specific version of a pipeline |\n\n### Dashboard Management\n\n| Tool | Description |\n|------|-------------|\n| `list_dashboards` | List all Perses dashboard definitions |\n| `create_dashboard` | Create or update a Perses dashboard definition |\n| `delete_dashboard` | Delete a dashboard definition |\n\n### Resources & Prompts\n\n- **Resources**: Browse tables via `greptime://<table>/data` URIs\n- **Prompts**: Built-in Jinja templates for common tasks — `pipeline_creator`, `log_pipeline`, `metrics_analysis`, `promql_analysis`, `trace_analysis`, `table_operation`, `schema_design_advisor`, `observability_correlation`, `ingestion_troubleshooting`, `query_performance_tuning`\n\nFor LLM integration and prompt usage, see [docs/llm-instructions.md](docs/llm-instructions.md).\n\n## Configuration\n\n### Environment Variables\n\n```bash\nGREPTIMEDB_HOST=localhost      # Database host\nGREPTIMEDB_PORT=4002           # MySQL protocol port (default: 4002)\nGREPTIMEDB_USER=root           # Database user\nGREPTIMEDB_PASSWORD=           # Database password\nGREPTIMEDB_DATABASE=public     # Database name\nGREPTIMEDB_TIMEZONE=UTC        # Session timezone\n\n# Optional\nGREPTIMEDB_HTTP_PORT=4000      # HTTP API port for pipeline/dashboard management\nGREPTIMEDB_HTTP_PROTOCOL=http  # HTTP protocol (http/https)\nGREPTIMEDB_POOL_SIZE=5         # Connection pool size\nGREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking\nGREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)\nGREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging\nGREPTIMEDB_ALLOW_WRITE=false   # Allow write/DDL via execute_sql (DANGEROUS, local/test only)\n\n# Transport (for HTTP server mode)\nGREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http\nGREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host\nGREPTIMEDB_LISTEN_PORT=8080    # HTTP server bind port\nGREPTIMEDB_ALLOWED_HOSTS=      # DNS rebinding protection (comma-separated)\nGREPTIMEDB_ALLOWED_ORIGINS=    # CORS allowed origins (comma-separated)\n```\n\n### CLI Arguments\n\n```bash\ngreptimedb-mcp-server \\\n  --host localhost \\\n  --port 4002 \\\n  --database public \\\n  --user root \\\n  --password \"\" \\\n  --timezone UTC \\\n  --pool-size 5 \\\n  --mask-enabled true \\\n  --allow-write false \\\n  --transport stdio\n```\n\n### HTTP Server Mode\n\nFor containerized or Kubernetes deployments:\n\n```bash\n# Streamable HTTP (recommended for production)\ngreptimedb-mcp-server --transport streamable-http --listen-port 8080\n\n# SSE mode (legacy)\ngreptimedb-mcp-server --transport sse --listen-port 3000\n```\n\n#### DNS Rebinding Protection\n\nBy default, DNS rebinding protection is **disabled** for compatibility with proxies, gateways, and Kubernetes services. To enable it, use `--allowed-hosts`:\n\n```bash\n# Enable DNS rebinding protection with allowed hosts\ngreptimedb-mcp-server --transport streamable-http \\\n  --allowed-hosts \"localhost:*,127.0.0.1:*,my-service.namespace:*\"\n\n# With custom allowed origins for CORS\ngreptimedb-mcp-server --transport streamable-http \\\n  --allowed-hosts \"my-service.namespace:*\" \\\n  --allowed-origins \"http://localhost:*,https://my-app.example.com\"\n\n# Or via environment variables\nGREPTIMEDB_ALLOWED_HOSTS=\"localhost:*,my-service.namespace:*\" \\\nGREPTIMEDB_ALLOWED_ORIGINS=\"http://localhost:*\" \\\n  greptimedb-mcp-server --transport streamable-http\n```\n\nIf you encounter `421 Invalid Host Header` errors, either disable protection (default) or add your host to the allowed list.\n\n## Security\n\n### Read-Only Database User (Recommended)\n\nCreate a read-only user in GreptimeDB using [static user provider](https://docs.greptime.com/user-guide/deployments-administration/authentication/static/#permission-modes):\n\n```\nmcp_readonly:readonly=your_secure_password\n```\n\n### Application-Level Security Gate\n\nAll queries go through a security gate that:\n- **Blocks**: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY\n- **Blocks**: Encoded bypass attempts (hex, UNHEX, CHAR)\n- **Allows**: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION\n\n### Write Mode (Disabled by Default)\n\nThe server is **read-only by default**. For local development or testing, you can\nallow write/destructive SQL (DDL/DML such as `CREATE`, `DROP`, `ALTER`, `INSERT`,\n`UPDATE`, `DELETE`) through the `execute_sql` tool by enabling write mode:\n\n```bash\n# Environment variable\nGREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server\n\n# Or CLI argument\ngreptimedb-mcp-server --allow-write true\n```\n\nWhen enabled, the security gate is **bypassed** for `execute_sql`, and the server\nlogs a warning on startup.\n\n> ⚠️ **Danger**: This lets an AI assistant run destructive statements against your\n> database. Never enable it against production data. Combine with a read-only\n> database user if you only need read access.\n\n### Data Masking\n\nSensitive columns are automatically masked (`******`) based on column name patterns:\n- Authentication: `password`, `secret`, `token`, `api_key`, `credential`\n- Financial: `credit_card`, `cvv`, `bank_account`\n- Personal: `ssn`, `id_card`, `passport`\n\nConfigure with `--mask-patterns phone,email` to add custom patterns.\n\n### Audit Logging\n\nAll tool invocations are logged:\n\n```\n2025-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\n```\n\nDisable with `--audit-enabled false`.\n\n## Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git\ncd greptimedb-mcp-server\nuv venv && source .venv/bin/activate\nuv sync\n\n# Run tests\npytest\n\n# Format & lint\nuv run black .\nuv run flake8 src\n\n# Debug with MCP Inspector\nnpx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server\n```\n\n## License\n\nMIT License - see [LICENSE.md](LICENSE.md).\n\n## Acknowledgement\n\nInspired by:\n- [ktanaka101/mcp-server-duckdb](https://github.com/ktanaka101/mcp-server-duckdb)\n- [designcomputer/mysql_mcp_server](https://github.com/designcomputer/mysql_mcp_server)\n- [mikeskarl/mcp-prompt-templates](https://github.com/mikeskarl/mcp-prompt-templates)\n",
  "bytes": 9184,
  "sha": "bbaab525969550858a420063a229ccc46859e6b4f12c5c77321897ce2344de49",
  "repo_slug": "greptimeteam/greptimedb-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_greptimeteam_greptimedb_mcp_se_872fce47/readme"
}