peaka-mcp-server

peaka-mcp-server

模型上下文协议（MCP）是一种新的标准化协议，用于管理大语言模型（LLM）与外部系统之间的上下文。

Peaka 模型上下文协议服务，提供对 Peaka text2SQL 功能的访问。

此服务使 LLM 能够检查架构，并在指定的 Peaka 项目上执行 SQL 查询。

组件

资源

• peaka_sql_query_rule_set
  • Peaka SQL 查询规则集是编写 Peaka SQL 查询的指南。
• peaka_artifact_template
  • 用于根据 Peaka 查询结果生成可视化报告、仪表板和工件的风格指南与 HTML 模板。

工具

所有项目范围的工具都需要 projectId 参数。如果 MCP 客户端尚不知道 projectId，应先调用 peaka_list_projects，再将选定的 ID 传递给后续调用。服务本身不会保留项目选择状态——每次调用都需携带自己的 projectId。

• peaka_list_projects
  • 列出当前 API 密钥可访问的所有项目。对于 Partner API 密钥，会枚举所有组织和工作区中的项目。对于 Project API 密钥，则返回与该密钥绑定的单个项目。
• peaka_query_golden_sqls
  • 从 Peaka 的黄金 SQL 向量存储中查询问题/SQL 对。如果现有查询与用户的问题匹配，可以直接复用。
• peaka_execute_sql_query
  • 在 Peaka 上运行给定的 SQL 查询。
• peaka_get_project_metadata
  • 在一次调用中获取 Peaka 项目中所有目录、架构和表的元数据。可选按 catalogId 和/或 schemaName 进行筛选。
• peaka_list_catalogs
  • 列出 Peaka 项目中的所有可用目录。返回目录名称、类型和连接信息。
• peaka_list_schemas
  • 列出 Peaka 项目中指定目录的所有可用架构。
• peaka_list_tables
  • 列出 Peaka 项目中指定目录和架构的所有可用表。
• peaka_list_columns
  • 列出 Peaka 项目中指定表的所有列。返回列名、数据类型和约束。
• peaka_get_relations
  • 获取目录的表关系（外键）。有助于构建准确的 JOIN。
• peaka_get_table_statistics
  • 获取表的列级统计信息，包括每列的不同值占比。
• peaka_create_cache
  • 为 Peaka 项目中的表创建缓存。缓存表会将数据存储在本地，从而提升查询性能。
• peaka_create_cache_batch
  • 在一次调用中为多个表创建缓存。与重复调用 peaka_create_cache 相比，优先使用此工具。
• peaka_get_cache_statuses
  • 获取 Peaka 项目中所有表的缓存状态，包括当前缓存状态、执行历史和进度。
• peaka_refresh_cache_full
  • 触发对现有缓存的完整刷新。
• peaka_refresh_cache_incremental
  • 触发对现有缓存的增量更新，仅获取新增或更改的行。
• peaka_update_cache
  • 更新现有缓存的设置（计划）。每次调用都会完全替换所有计划。
• peaka_delete_cache
  • 删除现有缓存；不会影响底层表。
• peaka_list_queries
  • 列出 Peaka 项目中所有已保存的查询。返回查询名称、SQL 内容，以及查询是普通查询还是物化查询。
• peaka_get_query
  • 根据 ID 读取单个已保存的查询。返回完整的查询对象，包括 SQL、类型和物化查询的刷新计划。
• peaka_execute_query
  • 在 Peaka 项目中根据 ID 执行已保存的查询。
• peaka_create_query
  • 在项目的语义层中创建命名并保存的查询。返回包含其 ID 的已创建查询。对于物化查询，可选提供 schedule 来设置自动刷新频率——{type: "interval", repeatDuration: "PT6H"}、{type: "cron", cronExpression: "0 0 * * *", timezone: "UTC"}，或 {type: "none"} 以禁用。
• peaka_update_query
  • 更新现有已保存查询的显示名称、SQL 正文和/或自动刷新 schedule（间隔、cron，或 {type: "none"} 以禁用；仅适用于物化查询）。
• peaka_delete_query
  • 从 Peaka 项目中删除已保存的查询。
• peaka_refresh_materialized_query
  • 触发对已保存物化查询的刷新。使用 peaka_list_queries 查找 queryType 为 MATERIALIZED 的查询 ID。
• peaka_get_materialized_query_statuses
  • 检查物化查询的自动刷新状态：上次刷新状态、上次/下次计划执行时间和计划设置。传入 queryId 可查看单个查询；省略则列出所有查询。
• peaka_list_connections
  • 列出 Peaka 项目中的所有数据源连接，包括每个连接的 ID、名称和类型。
• peaka_get_connection_detail
  • 获取数据源连接的专属配置信息。
• peaka_create_semantic_catalog
  • 在 Peaka 项目中创建语义目录。语义目录会将语义表（作为可查询表呈现的已保存查询）归入单个命名空间。
• peaka_create_semantic_table
  • 在语义目录中创建由已保存查询支持的语义表。需要提供 catalogId、schemaName、tableName 和 queryId。
• peaka_delete_semantic_table
  • 从语义目录中删除语义表。不会影响底层已保存查询。
• peaka_refresh_project_metadata
  • 刷新指定目录的项目元数据。此操作耗时较长；它会触发刷新并轮询直至完成。
• peaka_get_metadata_refresh_status
  • 检查指定目录的元数据刷新任务的当前状态。

与 Claude Desktop 配合使用

• 编辑配置文件 config.json：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
• 将以下配置添加到 mcpServers 对象中：

{
  "mcpServers": {
    "peaka": {
      "command": "npx",
      "args": ["-y", "@peaka/mcp-server-peaka@latest"],
      "env": {
        "PEAKA_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

将 {PEAKA_API_KEY} 替换为你的项目 API 密钥。请查阅 Peaka 文档以了解如何创建 API 密钥，并点击此处查看详细说明。

• 重启 Claude Desktop

打包为 Claude Desktop 扩展

此代码库附带一个 pack 脚本，用于构建服务，然后运行 mcpb pack（来自 @anthropic-ai/mcpb），生成 .mcpb 捆绑包。这是一个类似 zip 的归档文件，包含构建后的服务和 manifest.json，Claude Desktop 可将其作为自定义 MCP 扩展加载。

npm run pack

此操作会在代码库根目录生成 peaka-mcp-server.mcpb。要安装它，请打开 Claude Desktop → 设置 → 扩展 -> 高级设置 -> 安装扩展 -> 选择 .mcpb 文件 -> 根据提示输入 API 密钥并启用扩展。

环境变量

你可以使用以下环境变量进行配置：

名称	描述	默认值
PEAKA_API_KEY	用于向 Peaka 服务进行身份验证的项目 API 密钥（stdio 模式）。	-
PARTNER_API_BASE_URL	Peaka 合作伙伴 API 的基础 URL	https://partner.peaka.studio/api/v1
OAUTH_ISSUER	授权服务器颁发者，用于验证传入访问令牌的 iss 声明（httpStream 模式，必需）。	-
OAUTH_JWKS_URI	用于验证访问令牌签名的授权服务器 JWKS 端点（httpStream 模式，必需）。	-
OAUTH_REQUIRED_SCOPE	访问令牌必须包含的范围，令牌才会被接受（httpStream 模式）。	user_access
OAUTH_RESOURCE	预期的令牌受众（此 MCP 服务的资源 URL）。设置后，aud 不匹配的令牌将被拒绝。在授权服务器将 aud 绑定到该资源之前，请勿设置。	-

请求超时（httpStream）

Partner API 请求超时默认为 60 秒。可通过 MCP 端点 URL 上的 timeoutSeconds 查询参数按连接覆盖此设置 — 例如 https://mcp.peaka.studio/mcp?timeoutSeconds=120。这样，无需重新构建，即可通过 URL 为较慢的部署或本地部署调整超时时间。

最大值为 600 秒（10 分钟）。如果值超过最大值，或缺失／无效（非数字、零或负数），则会回退到 60 秒默认值，而不是截断到最大值 — 因此，像 timeoutSeconds=60000 这样的单位错误（本意是毫秒）不会导致请求持续数小时。

联系方式

如需提出功能请求或报告错误，请在此代码库中创建问题。如需进一步支持，请参阅以下资源：

• Peaka 社区 Discord