Knowi

Knowi MCP 服务

将 Claude Code、Claude Desktop、Cursor 或任何兼容 MCP 的 AI 客户端连接到 Knowi。直接通过 AI 助手使用自然语言查询数据、创建仪表板、管理报告等。

MCP 服务内置于 Knowi 应用中，无需单独安装。

快速开始

1. 生成 MCP 令牌

1. 登录 Knowi
2. 前往 设置 → AI 设置
3. 在 MCP 令牌下，选择有效期并点击 生成令牌
4. 复制令牌 — 它只会显示一次

2. 连接到 Claude Code

claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

对于 knowi.com 账户：

claude mcp add knowi https://www.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_MCP_TOKEN"

3. 连接到 Claude Desktop

编辑配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "knowi": {
      "type": "streamable-http",
      "url": "https://your-instance.knowi.com/api/2.0/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

保存后重启 Claude Desktop。

4. 验证

"What Knowi tools are available?"

你应该能看到 knowi_do、knowi_ask、knowi_search、knowi_list_dashboards 等工具。

---

可用工具

AI 驱动的工具

使用 Knowi 的 AI 编排器来理解指令并串联操作的自然语言工具。

工具	说明
knowi_do	通过自然语言执行任何 Knowi 操作
knowi_ask	提出数据问题 — 查找数据集、生成查询并返回结果
knowi_search	搜索所有仪表板、小组件、数据集和报告

确定性工具

直接、快速且行为可预测的操作。

工具	说明
knowi_list_dashboards	列出所有可访问的仪表板
knowi_get_data	从小组件或数据集检索数据行
knowi_push_data	向数据集推送数据行（如果数据集不存在，则创建它）
knowi_get_details	获取任何资源的完整元数据
knowi_find_widget	按名称查找小组件
knowi_create_datasource	创建新的数据源连接
knowi_create_query	创建并运行针对数据源的查询
knowi_create_widget	创建新的图表或可视化内容
knowi_update_widget	更新现有小组件
knowi_create_report	创建定时报表
knowi_create_alert	创建数据警报
knowi_list_alerts	列出已配置的警报
knowi_test_alert	测试警报
knowi_update_alert	更新警报
knowi_run	触发查询或报告的执行
knowi_export_pdf	将仪表板或小组件导出为 PDF
knowi_export_csv	将数据导出为 CSV
knowi_get_embed_url	生成可嵌入的共享 URL
knowi_get_insights	获取针对小组件生成的 AI 洞察
knowi_layout_dashboard	排列仪表板上的小组件
knowi_import_file	将文件（CSV、Excel）导入为数据集
knowi_ingest_document	导入文档以供 AI 问答
knowi_ask_document	针对已导入的文档提问
knowi_extract_document_data	从文档中提取结构化数据
knowi_list_documents	列出已导入的文档
knowi_delete_document	删除已导入的文档
knowi_delete	删除资源（需要明确确认）

---

使用示例

"Show me my Knowi dashboards"

"Ask Knowi: what were our top customers by revenue last month?"

"Create a sales dashboard with revenue trends and top products"

"Search Knowi for dashboards related to customer analytics"

"Get the data from the Monthly Revenue widget"

"Export the Executive Summary dashboard to PDF"

"Push these sales records to a Knowi dataset called 'Daily Sales'"

"Set up a daily email report for the executive dashboard"

---

令牌管理

轮换令牌：

1. 前往 设置 → AI 设置 → MCP 令牌
2. 点击 撤销令牌
3. 生成新令牌并更新配置：

claude mcp remove knowi
claude mcp add knowi https://your-instance.knowi.com/api/2.0/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_NEW_TOKEN"

每位用户只能有一个令牌。 生成新令牌会自动撤销之前的令牌。

---

API 参考

MCP 服务同时提供 Streamable HTTP（供 MCP 客户端使用）和 REST 端点（供直接编程调用）。

健康检查

curl https://your-instance.knowi.com/api/2.0/mcp/health

{
  "status": "healthy",
  "toolCount": 28,
  "tools": ["knowi_do", "knowi_ask", "knowi_search", "..."],
  "activeSessions": 0
}

列出工具

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.knowi.com/api/2.0/mcp/tools

调用工具（REST）

curl -X POST https://your-instance.knowi.com/api/2.0/mcp/tools/call \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowi_list_dashboards",
    "arguments": {}
  }'

Streamable HTTP（JSON-RPC）

所有 MCP 客户端操作都使用 POST /api/2.0/mcp 和标准 JSON-RPC：

# Initialize
curl -X POST https://your-instance.knowi.com/api/2.0/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

响应中包含 Mcp-Session-Id 标头，供后续请求使用。

---

安全

• 凭据范围限制：MCP 令牌只能访问 MCP 端点，不能用于访问更广泛的 Management API。
• 每次请求均进行授权：每个工具都会在执行前验证经过身份验证的用户是否有权访问所请求的资源。
• 提示词注入防护：AI 驱动的工具会扫描指令，查找已知的注入模式，并在指令到达 AI 模型前拒绝这些指令。
• 破坏性操作防护：knowi_do 会拦截删除／移除／清除指令。删除操作必须使用专用的 knowi_delete 工具，并提供必需的 confirm: true 参数。
• 数据截断：knowi_get_data 和 knowi_ask 默认最多返回 100 行。
• 会话安全：Streamable HTTP 会话与经过身份验证的用户绑定。仅凭会话 ID 无法获得访问权限。

数据流

当 Claude 调用 Knowi MCP 工具时，工具响应（数据行、元数据、洞察）会返回给 Claude，并在 Anthropic 的基础设施上进行处理。这是 MCP 的固有特性：客户端必须接收结果才能据此采取行动。

如需最大限度地隔离数据，请使用 Knowi 内置的 AI Agent，而非 MCP。

---

故障排除

Claude 中未显示工具：

• 完全重启 Claude Code／Claude Desktop
• 验证服务可访问：curl https://your-instance.knowi.com/api/2.0/mcp/health
• 验证令牌有效：curl -H "Authorization: Bearer TOKEN" https://your-instance.knowi.com/api/2.0/mcp/tools

claude mcp list 中显示“Failed to connect”：

• 确认使用了 --transport http（Streamable HTTP 必需）
• 如果传输方式设置不正确，请移除并重新添加服务

401 错误：

• 令牌可能已过期或被撤销。请从 Settings → AI Settings 生成新令牌并更新配置。

工具调用返回拒绝访问：

• 您配置的令牌所属用户无权访问所请求的资源。
• 用于生产环境时，请创建一个具有最低所需权限的专用 Knowi 用户。

---

要求

• 已启用 AI Agents 的 Knowi 账户（Settings → AI Settings）
• Claude Code CLI、Claude Desktop 或任何兼容 MCP 的客户端

---

文档

• MCP 服务参考 — 完整的 API 参考、所有工具架构和安全模型
• Claude Code 设置指南 — 分步设置说明
• Knowi 文档 — 完整的产品文档

---

支持

• 文档： knowi.com/docs
• 支持： support.knowi.com
• 关于此仓库的问题： 提交 GitHub issue