FutureSearch MCP Server

FutureSearch MCP 服务

大多数用户无需在本地运行 MCP 服务。请使用托管的远程服务 https://mcp.futuresearch.ai/mcp — 它通过 OAuth 进行身份验证，无需 API 密钥。请参阅设置指南。以下说明适用于需要 API 密钥的自托管或高级使用场景。

FutureSearch 的 MCP（Model Context Protocol）服务：可验证的 AI 预测。FutureSearch 将关于未来的问题转化为概率、日期和数字，其准确性可通过我们在股票、预测市场、公开基准和预测竞赛中的公开记录进行验证（markets.futuresearch.ai、evals.futuresearch.ai）。

此服务可让助手预测：关于未来的问题的概率、日期或数字，以及你或其他人的决策结果。它还可以针对一个问题或表格中的每一行运行网络研究 Agent。

使用托管服务时，可将行作为 data 直接传入，或引用已上传的 artifact_id。通过 stdio 自行运行服务时，工具还接受本地 CSV 文件的绝对路径，并将结果写入你指定的路径。

以一次 MCP 调用来表示一个决策：每个结果占一行，一列用于列出选项，并在 context 中说明预测者无法查到的信息。

{
  "tool": "futuresearch_decision",
  "arguments": {
    "data": [
      {
        "question": "How many sitting parliamentarians will be listed on ControlAI's campaign statement on December 31, 2028?",
        "grant": ["$0 (no grant)", "$250k", "$1M"]
      }
    ],
    "alternatives_field": "grant",
    "forecast_type": "numeric",
    "output_field": "parliamentarians",
    "units": "parliamentarians",
    "context": "We are a family foundation deciding this quarter how much to give ControlAI. The gift would be unrestricted and announced publicly, and no other funder is waiting on our decision."
  }
}

安装

此服务需要 FutureSearch API 密钥。请前往 futuresearch.ai/app/api-key 获取（含 20 美元免费额度）。

Claude Desktop

从 GitHub Releases 页面下载最新的 .mcpb 安装包，并双击以在 Claude Desktop 中安装。设置过程中，系统会提示你输入 FutureSearch API 密钥。安装完成后，你可以在 Claude Desktop 中的 Chat、Cowork 和 Code 里使用 FutureSearch。

Cursor

在打开 cursor 前，在终端 shell 中设置环境变量。之后，你可能需要从 shell 重新打开 cursor。或者，也可以在 cursor 设置中直接写入 API 密钥，而不是使用硬编码的 ${env:FUTURESEARCH_API_KEY}

export FUTURESEARCH_API_KEY=your_key_here

手动配置

可以按照上文所述，在 shell 环境中设置 API 密钥，也可以直接将其写入下方配置。不同 MCP 客户端对环境变量插值的支持可能有所不同。

export FUTURESEARCH_API_KEY=your_key_here

将以下内容添加到 MCP 配置中。如果你已安装 uv：

{
  "mcpServers": {
    "futuresearch": {
      "command": "uvx",
      "args": ["futuresearch-mcp"],
      "env": {
        "FUTURESEARCH_API_KEY": "${FUTURESEARCH_API_KEY}"
      }
    }
  }
}

或者，使用 pip 安装（最好在 venv 中），并使用 "command": "futuresearch-mcp" 替代 uvx。

工作流

所有操作都遵循异步模式：

1. 启动 - 调用操作工具（例如 futuresearch_agent）以启动任务。该工具会立即返回任务 ID。
2. 监控 - 反复调用 futuresearch_progress(task_id) 检查状态。该工具会阻塞约 12 秒，以限制轮询频率。
3. 获取结果 - 任务完成后，调用 futuresearch_results(task_id, output_path) 将结果保存为 CSV。

可用工具

futuresearch_forecast

预测关于未来的问题。支持五种模式：二元概率、数值百分位数、日期百分位数、分类（为每个列出的结果提供一个概率），以及阈值模式（为每个列出的阈值条件提供一个概率）。

Parameters:
- forecast_type: "binary", "numeric", "date", "categorical", or "thresholded"
- context: (optional) What is true for the whole call: facts about who is deciding and their situation, and any instructions that apply to every row.
- effort_level: (optional) "low" or "high" (default; required for categorical/thresholded)
- output_field: Name of the forecast quantity (required for numeric/date)
- units: Units of the forecast quantity (required for numeric)
- categories_field: Column with each row's outcomes as a JSON array of strings (required for categorical)
- thresholds_field: Column with each row's threshold conditions as a JSON array (required for thresholded)

示例：“美国联邦储备委员会会在 2027 年 7 月之前降息吗？”

futuresearch_decision

预测某项决策的结果：在每个选项下，预测同一个结果，例如“如果我们分别投入 0 美元、30 万美元或 200 万美元，项目会在什么时候上线？”。决策可以由用户本人或其他人作出，例如公司、监管机构或政府。只要“如果”涉及某人作出的决策，就使用此工具，而不要使用带有 condition 的 futuresearch_forecast。

输入需要包含 question（每行一个结果）和一个列出该行选项的列。如果决策由用户本人作出，请将你已了解的用户信息放入 context：用户的规模、预算和时间安排、尝试过的方法，以及如果什么都不做会发生什么。预测器无法自行查询这些信息。

Parameters:
- data: Inline data as a list of row objects
- artifact_id: Alternatively, an artifact ID from a previous upload
- alternatives_field: Name of the column holding each row's alternatives as a JSON array
- forecast_type: "binary" (default), "numeric", or "date": the outcome type forecast under each alternative
- output_field: Name of the quantity being forecast (required for numeric and date)
- units: Units for the outcome (required for numeric)
- context: (optional) What is true for the whole call: facts about who is deciding and their situation, and any instructions that apply to every row.
- intervention: (optional) Intervention assumptions

请提供 data 或 artifact_id，但不能同时提供两者。

示例：本 README 顶部的决策调用。

futuresearch_multi_agent

深度并行研究：为每一行部署一组方向 Agent，分别探索不同角度，然后综合结果。当完整性或深度比每行成本更重要时使用，例如列举“欧洲所有 AI 初创公司”，或者答案需要针对不同来源、地理区域或方法并行调查时。

Parameters:
- task: What to research per row.
- directions: (optional) Up to 6 explicit research angles. Each should be a detailed, self-contained brief, not a short title. Auto-generated from task if omitted.
- response_schema: (optional) Output structure for the synthesized result. Defaults to {"answer": string}.
- effort_level: (optional) "low" (3 agents per row), "medium" (4, default), "high" (2 frontier agents, deeper but slower).

futuresearch_agent

对 CSV 的每一行运行网页研究 Agent。

Parameters:
- task: Natural language description of research task
- input_csv: Absolute path to input CSV
- response_schema: (optional) JSON schema for custom response fields

示例：“查找这家公司最新一轮融资及其领投方”

futuresearch_browse_lists

浏览可用的知名实体参考列表（S&P 500、FTSE 100、国家、大学等）。

Parameters:
- search: (optional) Search term to match list names
- category: (optional) Filter by category (e.g. "Finance", "Geography")

futuresearch_use_list

将参考列表导入会话，并通过 artifact_id 提供给其他 futuresearch 工具使用。

Parameters:
- artifact_id: artifact_id from futuresearch_browse_lists results

futuresearch_upload_data

从 URL 或本地文件上传数据。返回一个供处理工具使用的 artifact_id。

Parameters:
- source: HTTP(S) URL (Google Sheets supported) or local CSV path (stdio mode only)
- session_id / session_name: (optional)

futuresearch_progress

检查正在运行的任务的进度。

Parameters:
- task_id: The task ID returned by an operation tool

调用后会等待约 12 秒再返回状态。请重复调用，直到任务完成。

futuresearch_results

检索并保存已完成任务的结果。

Parameters:
- task_id: The task ID of the completed task
- output_path: Full absolute path to output CSV file (must end in .csv)

只有在 futuresearch_progress 报告状态为 "completed" 后才调用。

futuresearch_cancel

取消正在运行的任务。

Parameters:
- task_id: Task ID to cancel

已弃用的工具

futuresearch_rank、futuresearch_classify、futuresearch_merge 和 futuresearch_dedupe 已弃用，将被移除。目前仍可使用。

开发

cd futuresearch-mcp
uv sync
uv run pytest

用于 MCP registry publishing：

mcp-name: io.github.futuresearch/futuresearch-mcp

许可证

MIT - 参见 LICENSE.txt