FactQL

factql-mcp

FactQLは、モデルを支えるハーネスです。

データについて質問してください。FactQLはクエリを実行し、回答を表示する前に結果を確認します。検証できない場合は推測せず、回答を控えます。

すべての回答には、実行したクエリ、返された行、そしてその根拠となるリネージュが含まれます。API呼び出しは1回です。Postgres、MySQL、DuckDB、アップロードしたCSVおよびXLSXファイル、引用付きで回答するPDFに対応しています。

実データの近くでAIを使う開発者向けに構築されています。間違った数値を自信たっぷりに提示できないAIアプリ、エージェント、社内ツールに最適です。

このパッケージは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