English Français العربية

FactQL

السجل الرسمي أخرى

Verified answers from your data, with the query and rows behind them, or a decline, never a guess.

الشيفرة المصدرية الموقع التوثيق

ماذا يمكنك أن تفعل مع FactQL؟

  • whoami() — the tenant, plan, and workspaces this key can query.
  • ask(question, workspace_id?, locale?) — the answer, the SQL that ran, and up to 50 rows. A needs_clarification result means the question was too vague; ask the user and call again with the detail. A declined result means FactQL couldn't verify an answ...

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package factql-mcp
Claude Code 
claude mcp add factql -e 'FACTQL_API_KEY=<your factql_api_key>' -e 'FACTQL_BASE_URL=https://api.factql.ai' -e 'FACTQL_WORKSPACE_ID=<FACTQL_WORKSPACE_ID>' -e 'FACTQL_END_USER_ID=<FACTQL_END_USER_ID>' -- uvx factql-mcp==0.1.2
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "factql": {
            "command": "uvx",
            "args": [
                "factql-mcp==0.1.2"
            ],
            "env": {
                "FACTQL_API_KEY": "<your factql_api_key>",
                "FACTQL_BASE_URL": "https://api.factql.ai",
                "FACTQL_WORKSPACE_ID": "<FACTQL_WORKSPACE_ID>",
                "FACTQL_END_USER_ID": "<FACTQL_END_USER_ID>"
            }
        }
    }
}

متغيرات البيئة

  • FACTQL_API_KEY إلزامي سري FactQL API key (an ask-only key is enough)
  • FACTQL_BASE_URL FactQL API base URL
  • FACTQL_WORKSPACE_ID Default workspace, for tenants that use workspaces
  • FACTQL_END_USER_ID Who is asking; defaults to mcp:<os user>

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. factql-mcp
  2. Get a key
  3. Install
  4. Configure
  5. Tools
  6. Safety
  7. Development
  8. License

factql-mcp

FactQL is the harness around the model.

Ask a question about your data. FactQL runs the query, checks the result before you see an answer, and declines instead of guessing when it can't verify.

Every answer ships with the query that ran, the rows it returned and the lineage behind it. One API call. Works with Postgres, MySQL, DuckDB, uploaded CSV and XLSX files, and PDFs with cited answers.

Built for developers putting AI near real data: AI apps, agents and internal tools that can't afford a confident wrong number.

This package is FactQL's MCP server: it brings those answers into Claude Desktop, Claude Code, Cursor, or any MCP client. Learn more at factql.ai.

Get a key

Sign up free at factql.ai/signup, connect your data, and create an API key. An ask-only key is enough for this server.

Install

uvx factql-mcp

or pip install factql-mcp.

Configure

VariableRequiredDefault
FACTQL_API_KEYyes— your FactQL API key (an ask-only key is enough)
FACTQL_BASE_URLnohttps://api.factql.ai
FACTQL_WORKSPACE_IDnodefault workspace, for tenants that use workspaces
FACTQL_END_USER_IDnomcp:<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

Tools

  • whoami() — the tenant, plan, and workspaces this key can query.
  • ask(question, workspace_id?, locale?) — the answer, the SQL that ran, and up to 50 rows. A needs_clarification result means the question was too vague; ask the user and call again with the detail. A declined result means FactQL couldn't verify an answer and gave none rather than guess; the reason says why. locale is en-GB or en-US.

Each ask is stateless: the MCP client carries the conversation, so a follow-up should restate what it refers to.

Safety

FactQL only runs SELECT queries, under a statement timeout, and only against the tables your admin has enabled. The key's permissions decide what it can see; this server adds nothing on top.

Development

uv run --with pytest pytest -q

License

MIT

الأسئلة الشائعة

ما هو FactQL؟

Verified answers from your data, with the query and rows behind them, or a decline, never a guess.

كيف أثبّت FactQL؟

يعمل على جهازك. في Claude Code: claude mcp add factql -e 'FACTQL_API_KEY=<your factql_api_key>' -e 'FACTQL_BASE_URL=https://api.factql.ai' -e 'FACTQL_WORKSPACE_ID=<FACTQL_WORKSPACE_ID>' -e 'FACTQL_END_USER_ID=<FACTQL_END_USER_ID>' -- uvx factql-mcp==0.1.2. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج FactQL إلى مفتاح API؟

نعم. يتطلب FACTQL_API_KEY، وتضبطها في إعداداته.

هل FactQL مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون FactQL؟

ينشره factql. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.