alpha-forge-mcp

The MCP server for [AlphaForge](https://alforgelabs.com) — the agent-native quant CLI: write strategies in JSON, optimize with Optuna TPE, validate with walk-forward, export to TradingView Pine v6. This server lets your AI agent drive the whole pipeline over MCP. → [Try AlphaForge free](https://alforgelabs.com)

A Model Context Protocol (MCP) server that exposes the AlphaForge `alpha-forge` CLI to AI coding agents — Claude Code, Cursor, Codex, and any MCP-capable client — over stdio.

It is a thin open-source wrapper: it shells out to the (commercial, closed-source) alpha-forge binary with --json and returns the parsed result. The MCP server itself contains no core logic — alpha-forge plus a valid license are required for anything to actually run.

Tools

save_strategy takes the strategy-definition JSON body as a string (not a file path, which is more agent-friendly); it is written to a temp file before strategy save. fetch_data exposes only period because the CLI has no --start/--end. forge_status is read-only and never fails when the binary is missing — it returns binary_found: false so a client can triage prerequisites before doing anything else.

run_optimize saves the result by default (save=true) so its saved_path can be passed to apply_optimization, which applies the optimized parameters and saves <strategy_id>_optimized (it runs non-interactively with --yes). get_indicator returns indicator metadata only (description, parameters, output) — the CLI has no compute-over-symbol command, so it does not calculate the indicator on price data. journal/explore reads are exposed read-first; write-oriented and ml/pairs commands are not exposed yet.

The metric argument of run_optimize / run_walk_forward is a constrained enum (sharpe_ratio (default), sortino_ratio, calmar_ratio, total_return_pct, cagr_pct, profit_factor, win_rate_pct, expectancy_pct, omega_ratio) so clients can pick a valid optimization target without guessing. This enum is intentionally narrower than the alpha-forge CLI's --metric, which accepts a wider set — it is curated to the bigger-is-better metrics that make sense as an optimization objective. trials defaults to 200 (the optimizer default). Each tool's description states its prerequisite (e.g. run_backtest needs fetch_data first; apply_optimization needs a run_optimize(save=true) result) and its follow-up.

Every argument also carries an inputSchema description, plus examples and constraints where they help: symbol shows exchange notation (AAPL, ^VIX, CL=F, USDJPY=X, BTC-USD), start / end advertise the YYYY-MM-DD pattern (format: date), trials / windows / simulations carry minimum: 1, and save_strategy(json_body) / apply_optimization(result_file) spell out "JSON body, not a path" vs "path, not inline JSON". Malformed arguments are rejected at the MCP boundary by schema validation.

The text-only (non---json) CLI wrappers return structured fields rather than only prose: apply_optimization adds applied_strategy_id (<strategy_id>_optimized, ready to pass to generate_pinescript), save_strategy returns the registered strategy_id, and fetch_data returns the fetched row count as rows (the raw output text is always kept).

Server instructions & long-running jobs

The server advertises instructions (surfaced in the MCP initialize response) describing the end-to-end workflow — forge_status → fetch_data → run_backtest → run_optimize → run_walk_forward → apply_optimization → generate_pinescript — so an agent knows which tools to call and in what order.

The run/fetch/save/apply tools are long-running (run_backtest up to 300 s, run_optimize / run_walk_forward up to 600 s, others bounded by the default timeout — stated in each tool's description). They report progress to capable clients via MCP progress notifications (a start → complete bracket; the underlying alpha-forge subprocess does not expose intermediate progress) and run the blocking call off the event loop so the server stays responsive. The timeout is enforced by alpha-forge; on expiry the tool returns the timeout error code, which is safe to retry.

All tools carry MCP tool annotations (readOnlyHint for the read tools — the list/ get lookups, generate_pinescript, forge_status, list_journals, get_journal, exploration_status, and get_indicator; openWorldHint for the run/write tools — run_backtest / run_optimize / run_walk_forward / run_monte_carlo, plus fetch_data (fetches external market data), save_strategy and apply_optimization (write to the DB)) and return structured output — structuredContent with an object outputSchema — alongside the text result.

Error envelope

Every tool returns a uniform error envelope as its (always-successful) result rather than raising, so an agent can branch on the failure category mechanically instead of parsing free text:

• Success: {"ok": true, "data": { ...alpha-forge JSON... }, "error": null}
• Failure: {"ok": false, "data": null, "error": {"code": "<category>", "message": "<summary>", "detail": "<raw context>"}}

error.code is the machine-readable failure category — e.g. forge_not_found (binary missing → guide setup), authentication_required (run alpha-forge system auth login), freemium_blocked (premium-only feature → stop), strategy_not_found, timeout (safe to retry), bad_output, execution_failed. error.message is a one-line summary; error.detail carries the raw context (forge stderr or the de-decorated freemium panel body, including the upgrade URL) when there is any, otherwise null. The outputSchema reflects this ok / data / error shape.

Resources

Read-only data is also exposed as MCP resources, so clients such as Claude Code can reference them by @-mention without an explicit tool call. They delegate to the same alpha-forge commands as the read tools and return application/json.

These mirror the read tools list_journals / get_journal / exploration_status / get_indicator. There is no forge://indicators collection resource because the CLI's indicator list is not wrapped as a tool/client method yet (only get_indicator is).

Prompts

Reusable workflows are exposed as MCP prompts (surfaced as /mcp__alpha-forge__<name> slash commands in Claude Code):

Streamable HTTP transport, RBAC, rate limiting, and audit logging are planned for a later release.

Prerequisites

1. The `alpha-forge` binary must be installed and on your PATH (or set ALPHA_FORGE_BIN).
2. You must be authenticated: run alpha-forge system auth login once.
3. Python 3.11+ (only needed if not using uvx).

Install & run

The recommended way is via uvx — no manual install needed; your IDE launches it on demand.

uvx alpha-forge-mcp        # starts the stdio MCP server

Or install explicitly:

pip install alpha-forge-mcp
alpha-forge-mcp

Claude Code

The easiest way is the claude mcp add command (user scope — available in every project):

claude mcp add --scope user alpha-forge -- uvx alpha-forge-mcp

Alternatively, add the server to a project-scoped .mcp.json at the repository root (checked in and shared with your team):

{
  "mcpServers": {
    "alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
  }
}

Note: Claude Code does not read ~/.claude/mcp.json. User-scoped servers are stored in ~/.claude.json (managed by claude mcp add); project-scoped servers live in .mcp.json at the project root.

Cursor / Codex

Use the same command / args in the client's MCP server configuration:

{
  "mcpServers": {
    "alpha-forge": { "command": "uvx", "args": ["alpha-forge-mcp"] }
  }
}

If alpha-forge is installed at a non-standard location, pass it via env:

{
  "mcpServers": {
    "alpha-forge": {
      "command": "uvx",
      "args": ["alpha-forge-mcp"],
      "env": { "ALPHA_FORGE_BIN": "/path/to/alpha-forge" }
    }
  }
}

Troubleshooting

• `forge_not_found` — ensure alpha-forge (or legacy forge) is on PATH, or set

ALPHA_FORGE_BIN=/path/to/alpha-forge.

• `authentication_required` — run alpha-forge system auth login. The MCP server does

not store credentials; it relies on alpha-forge's own auth.

Development

uv sync --extra dev
uv run pytest
uv run ruff check .

Forge binary discovery order: ALPHA_FORGE_BIN → PATH (forge, alpha-forge) → OS default install paths.

License

Apache License 2.0