forecast-mcp

Give your AI a Monte Carlo forecasting engine. A Model Context Protocol server that turns three-point estimates and historical throughput into calibrated, probabilistic forecasts: project timelines, cost ranges, and "when will it be done?" delivery dates.

Fully local. No API keys. No network calls.

---

Why this exists

Large language models are genuinely bad at probability. Ask one for a project deadline and it will confidently invent a single number, or "simulate" a distribution it cannot actually compute. Monte Carlo forecasting is exactly the kind of work an LLM should delegate to a tool: run thousands of seeded random trials and report the real distribution.

forecast-mcp gives any MCP-capable client (Claude Desktop, Claude Code, Cursor, and others) five tools to do that properly, so instead of "this will take about three weeks" you get:

P50 = 19.5 days, P80 = 24.1 days, P95 = 28.7 days, and an 84% chance of finishing within your 25-day target.

Install

Run it straight from npm with npx (no install needed):

npx forecast-mcp

Then register it with your client. For Claude Desktop / Claude Code, add to your MCP config:

{
  "mcpServers": {
    "forecast": {
      "command": "npx",
      "args": ["-y", "forecast-mcp"]
    }
  }
}

That's it. The server speaks stdio and needs no configuration, credentials, or internet access.

Running from source (before the npm package is published, or to hack on it): clone this repo, run npm install && npm run build, then point your client at it with "command": "node", "args": ["/absolute/path/to/forecast-mcp/dist/index.js"].

Tools

Tool	What it answers
forecast_duration	How long will the whole project take? (Monte Carlo over per-task 3-point estimates)
forecast_cost	What will it cost, with contingency? (Monte Carlo over cost line items)
forecast_completion	When will it be done, from our actual throughput? (flow-based, "no estimates")
pert_estimate	Quick analytical 3-point estimate + confidence levels (instant, no simulation)
sensitivity_analysis	Which tasks drive the uncertainty? (tornado-chart data)

Every tool takes optimistic / most-likely / pessimistic inputs (except forecast_completion, which uses throughput history) and returns both a human-readable summary and structured JSON.

Distributions

forecast_duration, forecast_cost, and sensitivity_analysis accept a distribution:

• pert (default) - beta-PERT, the project-management standard; weights the most-likely value.
• triangular - simple, bounded.
• normal - symmetric bell curve (std dev derived from the range).
• lognormal - right-skewed; models "usually fine, occasionally very late".
• uniform - flat between optimistic and pessimistic.

You can also override the distribution per item.

Reproducibility

Every tool accepts an optional seed and defaults to a fixed seed, so the same inputs always produce the same forecast. Change the seed to explore alternate random streams.

Deploying remotely (Streamable HTTP)

npx forecast-mcp is stdio-only, which is fine for a local client but can't be reached over a network. The same binary also speaks Streamable HTTP, so it can run as a standalone deployable service (Docker, Render, Fly, Railway, Cloud Run, a VM, etc.) that any remote MCP client can call.

One entry point, two transports - node dist/index.js picks the transport at runtime:

• No PORT and no MCP_TRANSPORT set -> stdio (the default, used by npx forecast-mcp).
• PORT set (most PaaS platforms set this automatically), or MCP_TRANSPORT=http -> Streamable HTTP, served at POST /mcp, with a GET /healthz health check.

The HTTP server is stateless: every request builds a fresh server instance (sessionIdGenerator: undefined, the pattern the MCP SDK recommends for this case). That's safe here because every forecast-mcp tool is a pure function - there is no session state to preserve between requests, so nothing is lost by not keeping one.

Run it locally over HTTP

npm run build
npm run start:http   # MCP_TRANSPORT=http PORT=3000 node dist/index.js
curl http://localhost:3000/healthz

Docker

docker build -t forecast-mcp .
docker run -p 3000:3000 forecast-mcp

The image always runs in HTTP mode (that is the point of containerizing it); most platforms inject their own PORT at deploy time, which overrides the image's default of 3000.

Environment variables (HTTP mode only)

Variable	Default	Purpose
PORT	3000	Port to listen on. Setting this alone is enough to switch to HTTP mode.
MCP_TRANSPORT	(unset)	Set to http to force HTTP mode even without PORT.
HOST	0.0.0.0	Interface to bind.
MCP_ALLOWED_HOSTS	(unset)	Comma-separated list of allowed Host header values, for DNS-rebinding protection when binding to a non-localhost address.

Security note

These tools are read-only pure computations with no filesystem, network, or credential access, so the blast radius of an unauthenticated call is low. Still, the server itself has no built-in authentication - if you expose it beyond a trusted network, put it behind a reverse proxy or gateway that handles auth, and set MCP_ALLOWED_HOSTS to suppress the DNS-rebinding warning.

Examples

forecast_duration

{
  "tasks": [
    { "name": "design", "optimistic": 2, "mostLikely": 4, "pessimistic": 8 },
    { "name": "build",  "optimistic": 5, "mostLikely": 10, "pessimistic": 30 },
    { "name": "test",   "optimistic": 1, "mostLikely": 3, "pessimistic": 6 }
  ],
  "unit": "days",
  "target": 25
}

returns P50/P80/P90/P95, mean, standard deviation, a distribution sparkline, and probabilityWithinTarget (~0.84).

forecast_completion ("when will it be done?")

{
  "throughputSamples": [4, 5, 6, 5, 4, 6],
  "backlog": 40,
  "periodLabel": "sprint",
  "startDate": "2026-07-13",
  "periodDays": 14
}

bootstraps future sprints from your last six and returns how many sprints (and which calendar dates) it will likely take to clear 40 items. Add splitRate to model scope creep.

sensitivity_analysis ranks the tasks by how much each one contributes to the total variance, so you know where tightening an estimate actually moves the needle.

Development

npm install
npm run build      # compile TypeScript to dist/
npm test           # build + run the vitest suite
npm run inspect    # open the MCP Inspector against the built server

The forecasting logic lives in src/engine/ (pure, dependency-free functions) and is exercised directly by the test suite; the tools in src/tools/ are thin MCP wrappers.

How it works

• Seeded PRNG (mulberry32) for reproducible trials.
• Beta-PERT sampling via two Gamma draws (Marsaglia-Tsang); triangular, normal (Box-Muller), lognormal, and uniform samplers included.
• Per-iteration line items are summed into a project total; percentiles are computed by linear interpolation over the sorted sample.
• sensitivity_analysis correlates each item's draws with the total (Pearson) and reports each item's share of variance.
• pert_estimate is a closed-form cross-check (its mean matches the simulation's mean to within a fraction of a unit).

License

MIT - see LICENSE.