alpha-forge-mcp

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.

⚠️ Pre-release / Alpha (`0.1.0aN`). Tool signatures and return formats may change without notice. Not recommended for production automation yet. Feedback welcome via Issues.

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

All tools carry MCP tool annotations (readOnlyHint for the read tools; openWorldHint for run_backtest / run_optimize, which fetch external market data) 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": "<human readable>", "detail": null}}

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. 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.

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