Forge MCP server

forge-mcp

Author, compile, run, and commit generative-music E-- Recipes directly from any MCP-capable agent (Claude Desktop, Cursor, …). forge-mcp exposes the Forge E-- library note catalog + vault as an MCP server and closes the authoring loop end-to-end: the agent picks a chip from the catalog, drafts a Recipe, verifies it parses, runs it in a sandbox, previews the artifact, and commits the finished Recipe to a vault note. All 6 tools ship today.

[library note catalog] → [compile] → [run] → [commit] → [vault note with recipe_version bump]

Install into Claude Code

Fastest path — Claude Code spawns forge-mcp as a stdio subprocess. Full walkthrough at docs/claude-code-install.md.

# 1. Install from PyPI (https://pypi.org/project/forge-recipe-mcp/)
pip install forge-recipe-mcp

# 2. Fetch your Bearer once and export
export FORGE_MCP_BEARER=$(jq -r '.transpileServiceToken' \
  ~/forge-vaults/bluh/.obsidian/plugins/forge-client-obsidian/data.json)

# 3. Register with Claude Code
claude mcp add forge-mcp \
  -e FORGE_MCP_BEARER=$FORGE_MCP_BEARER \
  -e FORGE_TRANSPILE_URL=https://forge.thecodingarena.com \
  -e FORGE_VAULT_PATH=$HOME/forge-vaults/bluh \
  -e FORGE_MCP_TRANSPORT=stdio \
  -- forge-mcp

# 4. Start Claude Code and ask "list the notes in my forge music library."

Install (other clients)

Full walkthrough (Claude Desktop config, forge-transpile Bearer acquisition, verification smoke, troubleshooting): docs/install.md.

Quick paths:

# From source (pip + editable install for development)
pip install -e ".[dev]"
python -m forge_mcp.server

# Docker
docker build -t forge-mcp:latest .
docker run --rm -p 8765:8765 \
    -e FORGE_TRANSPILE_URL=https://forge.thecodingarena.com \
    -e FORGE_VAULT_PATH=/path/to/your/vault \
    forge-mcp:latest

Environment:

• FORGETRANSPILEURL — base URL of the forge-transpile service. Default: http://localhost:8000.
• FORGEVAULTPATH — local vault directory for forgereadnotesinvault + forgecommitrecipe. Default: ~/forge-vaults/bluh.
• FORGEMCPHOST — host to bind. Default: 0.0.0.0.
• FORGEMCPPORT — port to bind. Default: 8765.
• FORGEMCPBEARER — dev fallback only. Per-request Bearer extraction is the primary path (CW-MCP-1-B); this env var only fires when the incoming request has no Authorization header. Do NOT set in production.

Claude Desktop config

Add to ~/Library/Application Support/Claude/claudedesktopconfig.json:

{
  "mcpServers": {
    "forge-mcp": {
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer <your-forge-transpile-token>"
      }
    }
  }
}

Get your Bearer:

jq -r '.transpileServiceToken' \
    ~/forge-vaults/bluh/.obsidian/plugins/forge-client-obsidian/data.json

Tools

Read (no side effects):

• forgereadnote_catalog({domain?}) — list Forge library notes; every entry carries the E-- signature the agent needs to Call it.
• forgereadnotesinvault({filter?}) — list vault notes with a hasrecipe + recipeversion summary. Backed by a local filesystem walk (CW-MCP-2-E).

Author (deterministic — no LLM, no vault write):

• forgecompilerecipe({source}) — Recipe → Python. Returns compiled source + unresolved slot count, OR a structured parse error with line/column (per drain CW-recipe-parser-line-info).
• forgerunrecipe({source, domains?}) — compile + execute in a resource-limited server sandbox. Returns a short preview + a run_id; artifacts (MusicXML / MIDI / PNGs) accessible via the forge-artifact:// resource.
• forgegetrunresult({runid}) — fetch full stdout/stderr + artifact manifest of a previous run. 7-day TTL, per-Bearer isolation.

Commit:

Shortened. The full README is on GitHub.