FactQL

factql-mcp

FactQL 是模型周围的运行框架。

询问有关数据的问题。FactQL 会运行查询，在你看到答案前检查结果；如果无法验证，就会拒绝回答，而不是猜测。

每个答案都附带实际运行的查询、返回的行以及背后的数据沿袭。只需一次 API 调用。支持 Postgres、MySQL、DuckDB、上传的 CSV 和 XLSX 文件，以及可提供引用答案的 PDF。

专为需要让 AI 接触真实数据的开发者打造：AI 应用、Agent 和内部工具都不能承受自信却错误的数字。

此软件包是 FactQL 的 MCP 服务：它可将这些答案带到 Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端中。了解更多信息，请访问 factql.ai。

托管服务（无需安装）

FactQL 也会为你运行此服务，地址如下：

https://api.factql.ai/mcp

在 Claude（Settings → Connectors → Add custom connector；支持网页、桌面和移动端）、Claude Code（claude mcp add --transport http factql https://api.factql.ai/mcp）、Cursor、VS Code 或任何支持远程 MCP 的应用中，将其添加为远程（Streamable HTTP）MCP 服务。应用会打开 FactQL 登录页面；点击 Allow，之后应用中的问题就会以你的身份运行。你可以在 factql.ai 的 Settings → Connected apps 下断开连接。无法登录的应用可以改为通过 Authorization: Bearer fl_live_... 发送 API 密钥。

各应用的设置说明：docs.factql.ai/guides/mcp。

本 README 的其余部分介绍如何自行运行该服务。

获取密钥

在 factql.ai/signup 免费注册，连接数据并创建 API 密钥。此服务只需使用仅允许提问的密钥。

安装

uvx factql-mcp

或运行 pip install factql-mcp。

配置

变量	必填	默认值
FACTQL_API_KEY	是	— 你的 FactQL API 密钥（仅允许提问的密钥即可）
FACTQL_BASE_URL	否	https://api.factql.ai
FACTQL_WORKSPACE_ID	否	默认工作区，适用于使用工作区的租户
FACTQL_END_USER_ID	否	mcp:<os user>

Claude Desktop / Cursor（mcpServers）

{
  "mcpServers": {
    "factql": {
      "command": "uvx",
      "args": ["factql-mcp"],
      "env": { "FACTQL_API_KEY": "fl_live_..." }
    }
  }
}

Claude Code

claude mcp add factql -e FACTQL_API_KEY=fl_live_... -- uvx factql-mcp

工具

• whoami() — 查询此密钥可访问的租户、计划和工作区。
• ask(question, workspace_id?, locale?) — 返回答案、实际运行的 SQL 以及最多 50 行数据。needs_clarification 结果表示问题太含糊；请询问用户并补充细节后再次调用。declined 结果表示 FactQL 无法验证答案，因此拒绝回答而不是猜测；reason 会说明原因。locale 为 en-GB 或 en-US。

每次 ask 调用都是无状态的：MCP 客户端会保留对话，因此后续问题应重新说明所指内容。

安全性

FactQL 只会运行 SELECT 查询，并设置语句超时；查询范围仅限管理员启用的表。密钥的权限决定它能查看哪些内容；此服务不会额外增加任何权限。

开发

uv run --with pytest pytest -q

许可证

MIT