/futuresearch-python

name: futuresearch-python
description: Use when the user wants forecasts (probabilities, dates, numbers, odds) or dataset research at scale via FutureSearch.

FutureSearch Python SDK

FutureSearch turns questions about the future into forecasts, with dataset research tools around it. Use this skill when writing Python code that needs to:

> **Documentation**: For detailed guides, case studies, and API reference, see: > - Docs site: [futuresearch.ai/docs](https://futuresearch.ai/docs) > - GitHub: [github.com/futuresearch/futuresearch-python](https://github.com/futuresearch/futuresearch-python)

**Operations:**

• Forecast probabilities, numbers, dates, and categories for questions about the future
• Forecast the outcome under each alternative of a decision you control
• Research one question with a team of parallel agents
• Run AI agents over dataframe rows
• Rank/score rows based on qualitative criteria
• Deduplicate data using semantic understanding
• Merge tables using AI-powered matching
• Classify rows into predefined categories

Installation

Python SDK

pip install futuresearch

MCP Server (for Claude Code, Claude Desktop, Cursor, etc.)

If an MCP server is available (`futuresearch_classify`, `futuresearch_rank`, etc. tools), you can use it directly without writing Python code. The MCP server operates on uploaded data (via artifact IDs or inline JSON).

To install the MCP server, add to your MCP config:

{
  "mcpServers": {
    "futuresearch": {
      "type": "http",
      "url": "https://mcp.futuresearch.ai/mcp"
    }
  }
}

Config file locations:

• **Claude Code**: `~/.claude.json` (user) or `.mcp.json` (project)
• **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
• **Cursor**: `~/.cursor/mcp.json`

When to Use SDK vs MCP

**Use MCP tools** when:

• Quick one-off operations on CSV files
• User wants direct results without writing code
• Simple lookups and enrichments

**Use Python SDK** when:

• Complex multi-step workflows (dedupe → merge → research)
• Custom data transformations
• Integration with existing Python scripts
• Full control over execution and intermediate results

---

MCP Server Tools

If you have the FutureSearch MCP server configured, these 18 tools are available. All data processing tools accept input via `artifact_id` (from upload_data or request_upload_url) or `data` (inline JSON rows). Provide exactly one.

Core Operations

futuresearch_forecast

Forecast questions about the future. Five outcome types: binary probabilities, numeric percentiles, date percentiles, categorical (one probability per listed outcome), and thresholded (one probability per listed threshold condition). Any of them can be made conditional on a stated intervention by supplying a condition (see "Conditional forecasting" below).

Parameters:
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects (must include "question" column)
- forecast_type: "binary", "numeric", "date", "categorical", or "thresholded" (always the OUTCOME type)
- context: (optional) Batch-level context for all questions
- effort_level: (optional) "low" or "high" (default; required for categorical/thresholded and for any conditional forecast)
- 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)
- condition: (optional) Single shared condition string mapped over every row, making the forecast conditional on it
- condition_field: (optional) Name of a per-row column holding each row's own condition (mutually exclusive with condition)
- session_id / session_name: (optional)

**Conditional forecasting.** Conditionality is a modifier on any forecast type, not a type of its own. Whenever the user frames a question with a condition or intervention ("if A…", "given/assuming A", "conditional on A", "in the world where A"), pick `forecast_type` from the outcome as usual (`date` for "when will X", `numeric` for "what will the return be", `binary` for "will X happen", etc.) and add the condition. Conditional forecasts are HIGH effort only. Each output keeps the type's normal columns and produces them a second time, suffixed `_given_condition` (the world where the condition holds) and `_given_not_condition` (where it does not), so the two branches reflect one coherent view of how the condition bears on the outcome, plus a `rationale`.

Two mutually exclusive ways to supply the condition:

• **Shared condition** (`condition`): a single condition string applied to every

row. Use it for a one-off question, or for the "ask the same conditional about each of these" case, where the user brings a list of entities and asks how one shared intervention moves each entity's outcome (e.g. *"for each company, what will its Q3 stock return be if Claude Fable launches worldwide before August?"*).

• **Per-row column** (`condition_field`): the name of an input column holding each

row's own condition, for a sheet where rows carry distinct conditions.

futuresearch_decision

Forecast the outcome under each alternative of a choice the user controls ("if I fund this at $0 / $300k / $2M, will it ship by 2027?"). The outcome under each alternative can be a probability, a number, or a date (`forecast_type` `binary` / `numeric` / `date`, as in futuresearch_forecast). Use this, whenever the "if" is the user's own decision: a conditional forecast is correlational, a decision is causal.

Parameters:
- artifact_id: Artifact ID (UUID) from upload_data or request_upload_url
- data: Inline data as a list of row objects (must include "question" column)
- alternatives_field: (required) Column holding