ephemeris-mcp

Ephemeris MCP is an MCP (Model Context Protocol) server that provides time series foundation model (TSFM) forecasting capabilities for AI agents. It enables Claude, Cursor, ChatGPT, or any MCP client to perform probabilistic forecasting with prediction intervals on numerical time series.

Purpose

Ephemeris is aimed at AI workflows that need numerical forecasting, typically including: sales, demand, inventory, website traffic, signups, revenue, energy load, prices, sensor readings, infrastructure metrics, and more. Users send historical data and receive quantile forecast results, with no training, no feature engineering, and no GPU required.

Main capabilities

• Runs a set of open-weight, zero-shot time series foundation models (TSFMs) behind a single API key, including Chronos-2, TimesFM 2.5, Toto 2, TiRex-2, and IBM Granite models.
• Provides an accuracy-weighted ensemble, i.e. a weighted fusion of the above model panel.
• Supports three usage modes: specifying a particular model, letting Ephemeris automatically route to the model best suited to the data, or using the ensemble.
• Returns quantile forecasts, i.e. results with prediction intervals.
• Benchmark performance: reaches a leading level on the TIME benchmark (MASE 0.639, top score 0.638), with the best average MASE ranking among 31 models; on GIFT-Eval, CRPS is 0.4662, outperforming every model it fuses (some leaderboard entries, including TimesFM-3, score better). Scoring uses each benchmark's own test framework.
• Provides the describe_forecast and plot_forecast tools, which can describe or plot saved forecast results (PNG by default, SVG can be specified); these two tools do not run inference and do not incur new forecast charges.
• Forecasts by default include an ephemeris.forecast v1 artifact, containing the submitted input history, response, billing information, and provided local context.
• Provides version diagnostics: MCP get_version can report the hosted server version, nullable build commit, and supported forecast modes, with no API key or inference charges required.

Usagemodes

Quick start (terminal)

Run the login command in the terminal, and Ephemeris will open in the browser. After logging in (or registering), confirm that the code shown on the page matches the terminal and approve. The key is saved to ~/.config/ephemeris/credentials, readable only by you; the stdio bridge will use it, and no key needs to be placed in the MCP configuration. The Ephemeris CLI (ephemeris auth login) and savetokens share the same file. npx ephemeris-mcp logout can delete that file; the key itself can be revoked on the API keys page of the dashboard.

You can also register at ephemeris.cascade.industries and create a key (pc_live_...) in the dashboard. Billing is per forecast, with no subscription.

Remote server (Streamable HTTP)

Address:https://ephemeris.cascade.industries/api/mcp，请求头 Authorization: Bearer pc_live_...

Client Integration

• Claude Code (plugin: MCP server plus a forecasting skill): will ask for an API key once, stored in the system secure credential store.
• Claude Code (server only): claude mcp add ephemeris -- npx -y ephemeris-mcp (uses the saved key).
• Cursor: one-click install, then replace YOUR_EPHEMERIS_API_KEY with your key in Cursor's MCP settings; or manually add to .cursor/mcp.json.
• VS Code: add to .vscode/mcp.json.
• Claude Desktop and other clients that only run local (stdio) servers: first run npx ephemeris-mcp login, no key needed in the configuration; you can also explicitly pass the key via "env": { "EPHEMERIS_API_KEY": "pc_live_your_key" }, which takes precedence over the saved key.
• OpenAI Responses API, Anthropic Messages API, Codex, Gemini CLI: see the documentation.

Usage Examples

After connecting, you can make the following requests:

• "This is my sales data for the past 18 months: ... Forecast the next 6 months, give an 80% interval."
• "Based on this CSV, forecast hourly traffic for next week, and find the step with the highest median forecast, but do not claim this is the actual peak distribution."
• "Use an ensemble to forecast daily signups for the next 90 days; plot the median and the 10th to 90th percentile band."

For more examples, see examples/prompts.md. Without using MCP, the same forecasts can be done with a single REST call: examples/rest_forecast.py.

Saved Forecasts and Updates

Keep an idempotency_key before submitting a paid MCP forecast. If the result is uncertain, you can retry with the same input and that key during the server's retention period; a new key or an expired key may incur additional charges. Treat the full saved object as an artifact is passed to describe_forecast or plot_forecast; neither accepts local paths or URLs. Artifact input is limited to 1 MiB; for larger local artifacts, use the CLI. If artifact_status is unavailable, retain the original successful result and the original request instead of paying to rerun.

Context and Billing Notes

When known, provide units, timezone, target definitions, and measurement semantics in context. Context reaches the hosted service but is not sent as model input. Ask about missing definitions; do not guess. The horizon counts sampling steps. Quantile bands are nominal marginal intervals: they do not establish calibrated coverage, cumulative intervals, path probabilities, or the actual peak distribution. Distinguish observed sales from latent demand, and known future inputs from scenario assumptions. A billing amount ending in _mc indicates millicredits (1000 mc = 1 credit).

Updates and Diagnostics

Hosted MCP updates are deployed centrally. If the client has cached the tool list, reconnect or start a new conversation. The existing npm bridge forwards new tools; update the bridge package only when the bridge itself changes. Client transport support and image/attachment rendering capabilities vary. The hosted endpoint uses Streamable HTTP; clients that only support SSE need compatible transport support.

Version diagnostics: MCP get_version with {} reports the hosted server version, nullable build commit, and supported forecast modes, without an API key or inference cost. ephemeris-mcp --version reports offline the installed npm bridge version, not the remote server version. The standalone CLI uses ephemeris --version or ephemeris version --json. These versions are independent of one another.

When to Use

• Sales, demand, and inventory forecasting
• Website traffic, signup, and revenue forecasting
• Energy load and price forecasting
• Sensor readings and infrastructure metric forecasting
• Forecasting in LangChain, OpenAI Agents SDK, and the Claude API

Limitations

• Quantile bands are nominal marginal intervals and do not establish calibrated coverage, cumulative intervals, path probabilities, or the actual peak distribution.
• Context reaches the hosted service but is not sent as model input.
• Artifact input is limited to 1 MiB.
• Client transport support and image/attachment rendering capabilities vary; clients that only support SSE need compatible transport support.
• Billing is per forecast, with no subscription; retries may incur additional charges.
• The code in the repository (plugin manifest, skills, and stdio bridge) is MIT licensed; each model retains its own license, as detailed on each model page.