← Back to Documentation

Metaculus

Browse Metaculus community forecasting questions, submit and withdraw forecasts, and track your own prediction record.

Tool Reference: 9 tools with full schemas →

Setup

Connect the Metaculus toolkit by configuring a Metaculus API token. Metaculus is a community forecasting platform; the toolkit lets your AI assistant browse questions, read what the community thinks, and, if you allow it, record forecasts under your own account.

Prerequisites

Before configuring the Metaculus toolkit, ensure you have:

• Configured an MCP server in your toolforest.io dashboard.
• A free Metaculus account.

Configuration Fields

Setup Steps

Prefer video? This 55-second walkthrough covers the whole setup, from the Prediction Markets tab to a configured toolkit:

Step 1: Create the API token

1. Sign in at metaculus.com.
2. Open Settings → Account → API access.
3. Copy your personal API token.

Step 2: Configure in toolforest.io

1. Open Toolforest and go to Toolkits.
2. Select the Prediction Markets tab.
3. Find Metaculus.
4. Click Configure.
5. Paste your Metaculus API token.
6. Submit the form.

The toolkit status will change to Configured, and your assistant can start browsing questions right away.

Once configured, a good first question to ask your assistant is what the token can actually see. The toolkit has a dedicated tool for exactly that, which probes how much community data comes back and whether bulk export works, so you learn your own access level rather than guessing at it.

Step 3: Allow forecasting (only if you want it)

Reading and forecasting are separate permissions on the Metaculus side. Your token covers reading; writing a forecast sits behind a second per-account switch that starts out disabled, and it is not something you can simply turn on in advance.

The switch has to be woken up first:

1. Ask your assistant to submit a forecast once. The attempt will be refused, which flips the setting from disabled to pending.
2. Go to Settings → Account → API forecasting access. Only in the pending state does the page show a one-button confirmation.
3. Confirm, and forecasts submitted through your assistant will be accepted from then on.

If you would rather forecast under a dedicated identity than your own, Metaculus supports bot accounts, created at Settings → Bots.

Managing Your Connection

Reconfigure

To update your API token, click the ⋮ (three-dot button) and select Reconfigure.

Disconnect

To disconnect the toolkit:

1. Click the Disconnect button in your MCP server panel.
2. toolforest.io will delete the stored API token.

Capabilities

Reading Metaculus data

Metaculus works differently from the other prediction-markets toolkits in ways that are easy to misread.

The community prediction is gated per response

Metaculus decides how much community forecast data to return based on your access tier, and it makes that decision response by response on its own side.

The toolkit therefore never guesses where the boundary sits. It asks for the community prediction every time and reports what came back, surfacing cp_access as either available or absent.

Read absent narrowly. It means the community prediction was not included in this response. It does not mean the question has no community forecast.

Your own data is not Community Prediction tier-gated

Personal forecasts and scores are account data. They are not tier-gated the way community data is, so your own forecast and my_scores can be present when the Community Prediction and community_scores are absent.

Access widens with use

Coverage is not fixed at signup, and this is unusual enough to be worth knowing:

• Forecasting on a question permanently unlocks that question for your account, including its full text and resolution details.
• The free Bot Benchmarking Access Tier widens community-prediction coverage. You apply through Metaculus’s Data Needs form, which the toolkit links directly from its own error hints when access is the reason a request came back thin. For the human path, Metaculus can be reached at api-requests@metaculus.com.

Posts and questions use different ids

The feed is made of posts. A post may hold a single question, a group of related questions, a conditional pair, or a notebook. get_question takes the post id from a Metaculus URL and returns every question inside it with its own question id.

Forecast writes use those question ids. submit_forecast requires one question id, and withdraw_forecast requires one or more question ids. For a group or conditional post, call get_question first and take the ids from its subquestions. Do not pass the post id as a substitute, even when a single-question post happens to use the same number.

submit_forecast.post_id is supplementary metadata for a continuous question whose owning post has a different id. It does not replace question_id.

What your own forecast record carries

For each question you have forecast on, your record carries a summary of your latest position rather than its full internal representation:

• start_time is when the latest forecast was made, not your first one on that question.
• end_time is the auto-withdrawal time, if you set one when submitting, or the moment you withdrew.
• withdrawn marks a forecast you have taken down.
• The value itself is compact and matches the question type: probability_yes on binary, option_probabilities on multiple choice, and a median plus a 25/75 interval on numeric, date, and discrete questions, given both raw and in the question’s own units.

The raw 201-value distribution behind a continuous forecast is never returned.

On a group or conditional post, the compact feed carries only one subquestion’s forecast and score, named by my_forecast_question_id. It does not summarise the whole group. Call get_question to inspect the forecast, resolution, and score for every subquestion.

Reading your scores

Once Metaculus has scored a question, my_scores contains:

• peer_score: your time-averaged score compared with the other forecasts on that question. Positive means better than the other forecasters on average; negative means worse.
• baseline_score: your time-averaged score compared with a fixed chance forecast. Positive means better than chance; negative means worse.
• spot_peer_score and spot_baseline_score: the same comparisons at one scoring time rather than across the question’s lifetime. These fields can be null; null means no spot score was returned, not a score of zero.
• relative_legacy_score: Metaculus’s older relative score, retained for questions and tournaments that still use it.
• coverage: the share of the question’s lifetime for which you had a forecast standing.
• weighted_coverage: Metaculus’s weighted coverage value when it supplies one. The toolkit preserves the upstream value rather than recalculating it.
• default_score_type: whether Metaculus treats spot or time-averaged scoring as primary for that question.

get_my_predictions(order_by="score") asks Metaculus to rank the rows by your performance on the server. The returned my_scores fields show how to interpret that order; do not infer performance from position alone.

get_question returns community_scores when the relevant community aggregation is present. Those scores may be absent when the Community Prediction is gated for the token, even though my_scores remains available.

Search and limits are best-effort

• Text search is not a documented feature. Metaculus’s OpenAPI describes no search parameter; the toolkit uses an undocumented one that may change or disappear. Treat discovery as primarily structured: filter by status, type, category, tournament, time range, and ordering.
• Rate limits are undocumented. If Metaculus returns a 429, the toolkit surfaces its message as-is rather than silently retrying.
• CSV export is restricted. When a download is refused, the toolkit returns an access hint explaining why, rather than a generic failure. Do not assume bulk export is available on every account.

Example prompts

The performance workflow uses get_my_predictions(statuses=["resolved"], order_by="score"); if a group appears, get_question expands it into its scored subquestions. The tournament workflow filters with not_forecaster_id; notebooks are not forecastable, so a notebook left in an otherwise complete tournament does not count as a missed question. The contract-review workflow uses get_question to read the resolution criteria, fine print, scheduled close, and current forecast together.

get_access_status samples Community Prediction coverage and probes CSV export. Its tier_suggestion is Toolforest’s interpretation of that sample, not a tier declared by Metaculus, and a sample can contain no Community Prediction data while personal forecasts and scores work normally.

The final example is a write. It requires the separate API forecasting access switch described in Setup; configuring a token alone does not grant permission to submit or withdraw forecasts.