AlphaForge MCP Server (alpha-forge-mcp) is a Model Context Protocol (MCP) server that exposes AlphaForge's alpha-forge command-line tool to AI coding agents via stdio, including Claude Code, Cursor, Codex, and any MCP-capable client.
Purpose The server lets AI agents drive the complete quantitative strategy workflow through MCP: write strategies in JSON, optimize with Optuna TPE, validate via walk-forward, export to TradingView Pine v6. It is itself a lightweight open-source wrapper: it invokes the commercially closed-source alpha-forge binary via --json and returns parsed results. The MCP server itself contains no core logic; running it actually requires alpha-forge and a valid license.
Main capabilities
- Tool set: save_strategy accepts a strategy definition JSON body (a string, not a file path, which is friendlier for agents), writes it to a temporary file, then runs strategy save. fetch_data only exposes period, because the CLI has no --start / --end. forge_status is read-only and does not fail when the binary is missing; it returns binary_found: false, making it easy for clients to first check prerequisites.
- run_optimize saves results by default (save=true), and its saved_path can be passed to apply_optimization, which applies the optimized parameters and saves <strategy_id>_optimized (running non-interactively with --yes). get_indicator only returns indicator metadata (description, parameters, output); the CLI has no calculation command for a symbol, so indicators are not computed on price data. journal/explore are exposed as read-only reads; write-type and ml/pairs commands are not yet exposed.
- The metric parameter of run_optimize / run_walk_forward is a restricted enum (sharpe_ratio (default),sortino_ratio, calmar_ratio, total_return_pct, cagr_pct, profit_factor, win_rate_pct, expectancy_pct, omega_ratio), making it easy for clients to choose a valid optimization target without guessing. This enum is intentionally narrower than the alpha-forge CLI's --metric (which accepts a broader set), keeping only the "larger is better" metrics suitable as optimization targets. trials defaults to 200 (the optimizer default). Each tool's description explains its prerequisites (e.g., run_backtest requires fetch_data first; apply_optimization requires the result of run_optimize(save=true)) and next steps.
- Every parameter has an inputSchema description, with examples and constraints where helpful: symbol shows exchange notation (AAPL, ^VIX, CL=F, USDJPY=X, BTC-USD), start / end declare the YYYY-MM-DD pattern (format: date), trials / windows / simulations have minimum: 1, and save_strategy(json_body) / apply_optimization(result_file) make clear "JSON body, not a path" and "path, not inline JSON". Malformed parameters are rejected by schema validation at the MCP boundary.
- The plain-text (non---json) CLI wrapper returns structured fields rather than only prose: apply_optimization adds applied_strategy_id (<strategy_id>_optimized, which can be passed directly to generate_pinescript), save_strategy returns the registered strategy_id, and fetch_data returns the number of rows fetched (the raw output text is always preserved).
Server instructions and long tasks The server declares instructions (presented 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—lets the agent know which tools to call and in what order. The run/fetch/save/apply tools are for long tasks (run_backtest up to 300 seconds, run_optimize / run_walk_forward up to 600 seconds, others are subject to the default timeout—described in each tool's description). They report progress to supporting clients via MCP progress notifications (start → complete brackets; the underlying alpha-forge subprocess does not expose intermediate progress), and move blocking calls off the event loop to keep the server responsive. Timeouts are enforced by alpha-forge; on expiry the tool returns a timeout error code, which is safe to retry. All tools carry MCP tool annotations (read-only tools carry readOnlyHint—list / get queries, generate_pinescript, forge_status, list_journals, get_journal, exploration_status, and get_indicator; run/write tools carry openWorldHint—run_backtest / run_optimize / run_walk_forward / run_monte_carlo, as well as fetch_data (fetches external market data), save_strategy, and apply_optimization (writes to the database)), and return structured output—structuredContent with an object outputSchema—as well as text results.
Error handling Every tool returns a unified error envelope as its (always successful) result instead of throwing an exception, making it easy for the agent to branch mechanically on the failure category without 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—for example forge_not_found (binary missing → bootstrap 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), or null if there is none. outputSchema reflects this ok / data / error structure.
Resources and prompts Read-only data is also exposed as MCP resources, so clients such as Claude Code can reference them via @ mentions without explicit tool calls. They delegate to the same alpha-forge commands as the read-only tools and return application/json. These resources mirror the read-only tools list_journals / get_journal / exploration_status / get_indicator. There is no forge://indicators collection resource, because the CLI's indicator list has not yet been wrapped as a tool/client method (only get_indicator). Reusable workflows are exposed as MCP prompts (presented in Claude Code as the /mcp__alpha-forge__<name> slash command). Streamable HTTP transport, RBAC, rate limiting, and audit logging are planned for future releases.
Usage Prerequisites: the alpha-forge binary must be installed and on PATH (or set ALPHA_FORGE_BIN). It must be authenticated: run alpha-forge system auth login once. Python 3.11+ (only inwhen not using uvx). The recommended way is via uvx—no manual installation required; the IDE starts it on demand. Or install explicitly. The simplest way is to use the claude mcp add command (user scope—available in every project). Alternatively, add the server to the project-scoped .mcp.json at the repository root (checked in and shared with the team). 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 are located in .mcp.json at the project root. Use the same command/arguments in the client's MCP server configuration. If alpha-forge is installed in a non-standard location, pass it in via env.
Troubleshooting forge_not_found—make sure alpha-forge (or the legacy forge) is in 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 authentication. Forge binary discovery order: ALPHA_FORGE_BIN → PATH (forge, alpha-forge) → OS default installation path.
License Apache License 2.0.
