跳到主要内容
版本：1.1

Model Context Protocol (MCP)

实验性功能

GreptimeDB MCP Server 目前处于实验阶段并在积极开发中。API 和功能可能会在没有通知的情况下发生变化。请在生产环境中谨慎使用。

GreptimeDB MCP Server 提供了模型上下文协议的实现，使 Claude 等 AI 助手能够安全地用 SQL、TQL（兼容 PromQL）和 RANGE 查询来查询与分析您的 GreptimeDB 数据库——并内置只读 SQL 校验和数据脱敏。

查看我们的演示视频和文章，了解 MCP Server 的实际应用效果。

什么是 MCP？​

模型上下文协议（MCP）是一种标准协议，允许 AI 助手与外部数据源和工具进行交互。通过 GreptimeDB MCP Server，AI 助手可以探索你的表、借助语义层理解每张表代表什么、执行查询，并管理 pipeline 和仪表盘。

工具​

该 server（v0.5.0）提供以下工具。

查询与检查​

工具说明
execute_sql执行 SQL 查询，支持格式（csv/json/markdown）和 limit 选项。
execute_tql执行 TQL（兼容 PromQL）查询进行时序分析。
query_range用 RANGE/ALIGN 语法执行时间窗口聚合查询。
describe_table检查表的 profile：schema、语义元数据、最新样本行、查询提示。
explain_query分析 SQL 或 TQL 查询的执行计划。
health_check检查数据库连接状态和 server 版本。

describe_table 会读取表语义层，因此 AI 助手能直接得到表的 signal type、source 和 metric 元数据，而不必从列名去猜。

Pipeline 管理​

工具说明
list_pipelines列出所有 pipeline，或获取某个 pipeline 的详情。
create_pipeline用 YAML 配置创建新的 pipeline。
dryrun_pipeline用样本数据测试 pipeline，不写入数据库。
delete_pipeline删除某个版本的 pipeline。

仪表盘管理​

工具说明
list_dashboards列出所有 Perses 仪表盘定义。
create_dashboard创建或更新 Perses 仪表盘定义。
delete_dashboard删除仪表盘定义。

server 还内置了一批 Jinja prompt 模板，覆盖常见任务（metrics 分析、trace 分析、pipeline 创建、schema 设计、查询性能调优等）。

安装​

pip install greptimedb-mcp-server

直接运行（默认连接 localhost:4002）：

greptimedb-mcp-server --host localhost --database public

配置​

server 通过环境变量或命令行参数配置。下表列出最常用的选项；HTTP server 模式还有额外参数。

环境变量命令行参数默认值说明
GREPTIMEDB_HOST--hostlocalhost数据库主机。
GREPTIMEDB_PORT--port4002MySQL 协议端口。
GREPTIMEDB_USER--userroot数据库用户。
GREPTIMEDB_PASSWORD--password—数据库密码。
GREPTIMEDB_DATABASE--databasepublic数据库名称。
GREPTIMEDB_TIMEZONE--timezoneUTC会话时区。
GREPTIMEDB_HTTP_PORT--http-port4000HTTP API 端口（用于 pipeline/仪表盘工具）。
GREPTIMEDB_MASK_ENABLED--mask-enabledtrue脱敏敏感列。
GREPTIMEDB_AUDIT_ENABLED--audit-enabledtrue记录每次工具调用。
GREPTIMEDB_ALLOW_WRITE--allow-writefalse允许通过 execute_sql 执行写/DDL，见下文写模式。
GREPTIMEDB_TRANSPORT--transportstdio传输方式：stdio、sse 或 streamable-http。

Claude Desktop 集成​

在 claude_desktop_config.json 中添加以下配置：

{
  "mcpServers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"],
      "env": {
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "your_username",
        "GREPTIMEDB_PASSWORD": "your_password"
      }
    }
  }
}

HTTP server 模式​

对于容器化或 Kubernetes 部署，可以用 HTTP 而非 stdio 运行 server（需要 mcp>=1.8.0）：

# Streamable HTTP（生产推荐）
greptimedb-mcp-server --transport streamable-http --listen-port 8080

# SSE 模式（旧版）
greptimedb-mcp-server --transport sse --listen-port 3000

为了兼容代理和 Kubernetes service，DNS rebinding 保护默认关闭。需要时用 --allowed-hosts 开启。

安全​

execute_sql 默认只读，server 还提供多重保护。

只读保证仅覆盖 execute_sql。pipeline 和 dashboard 工具（create_pipeline、delete_pipeline、create_dashboard、delete_dashboard）经由 HTTP API 访问 GreptimeDB，无论是否开启 --allow-write 都能修改这些资源。若要确保助手无法做出任何改动，请在数据库层面收紧权限，不要依赖这个开关。

  • 安全校验：拦截 DROP、DELETE、TRUNCATE、UPDATE、INSERT、ALTER、CREATE、GRANT、REVOKE 以及编码绕过尝试；放行 SELECT、SHOW、DESCRIBE、TQL、EXPLAIN、UNION。
  • 数据脱敏：列名匹配 password、token、api_key、ssn、credit_card 等模式的列会被脱敏为 ******。用 --mask-patterns 增加模式。
  • 审计日志：记录每次工具调用。用 --audit-enabled false 关闭。

为了获得最强的安全配置，还可以用静态用户 provider 创建一个只读数据库用户，并用它来连接 server。

写模式​

在本地开发或测试时，可以允许通过 execute_sql 执行写/DDL 语句（CREATE、DROP、ALTER、INSERT、UPDATE、DELETE）：

greptimedb-mcp-server --allow-write true

开启后，execute_sql 的安全校验会被跳过，server 启动时会打印警告。

危险

写模式会让 AI 助手对你的数据库执行破坏性语句。切勿在生产数据上开启。

了解更多​

有关高级用法和故障排除，请参阅 GreptimeDB MCP Server 文档。

备注

GreptimeDB MCP Server 是一个仍在开发中的实验性项目。在处理敏感数据时请谨慎使用。