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.6.1 提供以下工具。
查询与检查
| 工具 | 说明 |
|---|---|
execute_sql | 执行 SQL 查询(MySQL 方言)。format 可选 csv(默认)、json 或 markdown;limit 默 认为 1000 行,取值会被限制在 1–10000 之间。 |
execute_tql | 执行 TQL(兼容 PromQL)查询,参数为 query、start、end、step,以及可选的 lookback(默认 5m)。最多返回 10000 行。 |
query_range | 用 RANGE/ALIGN 语法执行时间窗口聚合查询。table、select 和 align 必填;by、where、fill 和 order_by 可选。 |
search_table_semantics | 按可观测性概念查找表,例如 redis memory usage。在一个数据库内搜索表名、语义选项和实体声明,按匹配的词数排序。可选参数为 signal_type、schema 和 limit(默认值和上限均为 50)。 |
query_semantic_graph | 查询语义图。view 可选 summary、entities 或 relationships;start_time 和 end_time(RFC 3339)指定必填的左闭右开时间窗口。实体和关系过滤条件可选;limit 默认为 100(上限 500)。 |
describe_table | 检查表的 profile:schema、语义元数据、样本行(默认 5 行,最多 20 行)和查询提示。 |
explain_query | 查看 SQL 查询或 TQL EVAL 语句的执行计划。analyze=true 会实际执行查询并返回运行时指标;verbose=true 额外返回按分区统计的扫描指标。 |
health_check | 检查数据库连接状态和 server 版本。 |
execute_sql、query_range 和 describe_table 可以用 schema.table 读取其他数据库;execute_tql 通过 __schema__ 匹配器读取其他数据库,例如 metric{__schema__="other_db"}。连接所用的用户需要具备该数据库的读权限。
describe_table 和 search_table_semantics 会读取表语义,因此 AI 助手能直接得到表的 signal type、source 和 metric 元数据,无需根据列名推断。search_table_semantics 只返回带有 greptime.semantic.* 选项、或由内置约定生成实体声明的表。实体声明需要 GreptimeDB v1.3 及以上版本。query_semantic_graph 读取 greptime_private.semantic_entities 和 greptime_private.semantic_relationships,同样需要 v1.3 及以上版本。如果 server 启动时这两个视图不存在,或连接用户无权读取,server 不会提供 query_semantic_graph。
工具返回结果的大小受 GREPTIMEDB_MAX_RESULT_BYTES 限制(默认 1 MiB)。超出限制的查询结果会减少返回行数,并注明结果已被截断。
Pipeline 管理
| 工具 | 说明 |
|---|---|
list_pipelines | 列出所有 pipeline,或获取某个 pipeline 的详情。 |
create_pipeline | 用 YAML 配置创建新的 pipeline 版本。需要开启写模式。 |
dryrun_pipeline | 用样本数据 测试内联或已保存的 pipeline,不写入数据库。 |
delete_pipeline | 删除某个版本的 pipeline。需要开启写模式。 |
仪表盘管理
| 工具 | 说明 |
|---|---|
list_dashboards | 列出所有 Perses 仪表盘定义。 |
create_dashboard | 创建或覆盖 Perses 仪表盘定义。需要开启写模式。 |
delete_dashboard | 删除仪表盘定义。需要开启写模式。 |
Resource 和 prompt
可以通过 greptime://<table>/data URI 以 resource 形式读取表数据,最多返回 100 行。
server 还内置了以下 Jinja prompt 模板:pipeline_creator、log_pipeline、metrics_analysis、promql_analysis、trace_analysis、table_operation、schema_design_advisor、observability_correlation、ingestion_troubleshooting 和 query_performance_tuning。