Enables AI agents to author, compile, run, and commit generative-music recipes directly to a local vault.
Also known as frmoded/forge-mcp, forge-mcp, forge-recipe-mcp
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- 99
- Latest version
- 0.2.0
- Last commit
- Oct 19, 2026
- License
- Apache-2.0
What is Forge MCP?
Forge enables AI agents to author, compile, run, and commit generative-music recipes directly to a local vault. It exposes 6 tools, such as forge_read_note_catalog, forge_read_notes_in_vault, forge_compile_recipe.
Summary generated from the project's README
About Forge MCP server
Forge MCP allows AI agents to manage the entire lifecycle of generative music creation. It connects an agent to a local music vault and a remote transpilation service, enabling the drafting, testing, and saving of music recipes. Developers can use this with Claude Desktop or Claude Code by configuring a Bearer token and specifying a local vault path. The server operates through a combination of local filesystem access for vault management and remote sandboxed execution for running music code.
The system provides six specific tools to close the authoring loop. Agents can browse a library catalog, compile recipes into Python, and execute them within a resource-limited sandbox to preview musical artifacts like MIDI or MusicXML. Once a recipe is verified, the agent can commit it back to a local vault note, which automatically increments the recipe version. This setup is designed for users who want to integrate algorithmic music composition directly into their AI-driven development workflows.
What you can do with it
- 1Browse music library componentsAsk the agent to list available notes and signatures from the Forge library catalog to find musical building blocks.
- 2Verify music recipe syntaxHave the agent compile a drafted music recipe to check for parsing errors before attempting to run it.
- 3Preview generated musical artifactsInstruct the agent to run a recipe in a sandbox and provide a preview of the resulting audio or notation files.
- 4Save completed recipes to a vaultTell the agent to commit a successful music recipe to a specific local note and update its version number.
Written from the project's README. Every use case is checked against a quote from it.
How to install Forge MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Forge MCP in Claude Code
$ claude mcp add --env 'FORGE_MCP_BEARER=<YOUR_FORGE_MCP_BEARER>' forge-mcp -- uvx forge-recipe-mcpInstall Forge MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"forge-mcp": {
"command": "uvx",
"args": [
"forge-recipe-mcp"
],
"env": {
"FORGE_MCP_BEARER": "<YOUR_FORGE_MCP_BEARER>"
}
}
}
}Install Forge MCP in VS Code
.vscode/mcp.json
{
"servers": {
"forge-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"forge-recipe-mcp"
],
"env": {
"FORGE_MCP_BEARER": "<YOUR_FORGE_MCP_BEARER>"
}
}
}
}Install Forge MCP in VS Code CLI
$ code --add-mcp '{"name":"forge-mcp","type":"stdio","command":"uvx","args":["forge-recipe-mcp"],"env":{"FORGE_MCP_BEARER":"<YOUR_FORGE_MCP_BEARER>"}}'Install Forge MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"forge-mcp": {
"command": "uvx",
"args": [
"forge-recipe-mcp"
],
"env": {
"FORGE_MCP_BEARER": "<YOUR_FORGE_MCP_BEARER>"
}
}
}
}Install Forge MCP in Codex
$ codex mcp add forge-mcp --env 'FORGE_MCP_BEARER=<YOUR_FORGE_MCP_BEARER>' -- uvx forge-recipe-mcpInstall Forge MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.forge-mcp] command = "uvx" args = ["forge-recipe-mcp"] [mcp_servers.forge-mcp.env] FORGE_MCP_BEARER = "<YOUR_FORGE_MCP_BEARER>"
Install Forge MCP in Gemini CLI
$ gemini mcp add -s user -e 'FORGE_MCP_BEARER=<YOUR_FORGE_MCP_BEARER>' forge-mcp uvx -- forge-recipe-mcpInstall Forge MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"forge-mcp": {
"command": "uvx",
"args": [
"forge-recipe-mcp"
],
"env": {
"FORGE_MCP_BEARER": "<YOUR_FORGE_MCP_BEARER>"
}
}
}
}Forge MCP tools 6
Detected from the READMEforge_read_note_catalogforge_read_notes_in_vaultforge_compile_recipeforge_run_recipeforge_get_run_resultforge_commit_recipe
| forge_read_note_catalog | — | |
| forge_read_notes_in_vault | — | |
| forge_compile_recipe | — | |
| forge_run_recipe | — | |
| forge_get_run_result | — | |
| forge_commit_recipe | — |
Configuration
FORGE_MCP_BEARERRequiredSecretBearer token forwarded to forge-transpile. Rotate by updating FORGE_TRANSPILE_SECRET on the upstream service and re-setting this. Dev fallback only when clients don't set Authorization on each request.
FORGE_TRANSPILE_URLBase URL of the forge-transpile service. Provides /catalog, /compile, /run, /resolve-slot endpoints backing the read/author tools.
FORGE_VAULT_PATHLocal vault directory used by forge_read_notes_in_vault + forge_commit_recipe. Must exist and be writable.
| Name | Description | |
|---|---|---|
| FORGE_MCP_BEARER | Bearer token forwarded to forge-transpile. Rotate by updating FORGE_TRANSPILE_SECRET on the upstream service and re-setting this. Dev fallback only when clients don't set Authorization on each request. | RequiredSecret |
| FORGE_TRANSPILE_URL | Base URL of the forge-transpile service. Provides /catalog, /compile, /run, /resolve-slot endpoints backing the read/author tools. | |
| FORGE_VAULT_PATH | Local vault directory used by forge_read_notes_in_vault + forge_commit_recipe. Must exist and be writable. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablefrmoded/forge-mcp is public and reachablegithub.com/frmoded/forge-mcp ↗Pass
- Package names this repository as its sourceforge-recipe-mcp names frmoded/forge-mcp as sourcepypi.org/project/forge-recipe-mcp/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-19github.com/frmoded/forge-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from forge-recipe-mcpPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubforge-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:
FORGE_TRANSPILE_URL— base URL of the forge-transpile service. Default:http://localhost:8000.FORGE_VAULT_PATH— local vault directory forforge_read_notes_in_vault+forge_commit_recipe. Default:~/forge-vaults/bluh.FORGE_MCP_HOST— host to bind. Default:0.0.0.0.FORGE_MCP_PORT— port to bind. Default:8765.FORGE_MCP_BEARER— 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 noAuthorizationheader. Do NOT set in production.
Claude Desktop config
Add to ~/Library/Application Support/Claude/claude_desktop_config.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):
forge_read_note_catalog({domain?})— list Forge library notes; every entry carries the E-- signature the agent needs toCallit.forge_read_notes_in_vault({filter?})— list vault notes with ahas_recipe+recipe_versionsummary. Backed by a local filesystem walk (CW-MCP-2-E).
Author (deterministic — no LLM, no vault write):
forge_compile_recipe({source})— Recipe → Python. Returns compiled source + unresolved slot count, OR a structured parse error with line/column (per drain CW-recipe-parser-line-info).forge_run_recipe({source, domains?})— compile + execute in a resource-limited server sandbox. Returns a short preview + arun_id; artifacts (MusicXML / MIDI / PNGs) accessible via theforge-artifact://resource.forge_get_run_result({run_id})— fetch full stdout/stderr + artifact manifest of a previous run. 7-day TTL, per-Bearer isolation.
Commit:
forge_commit_recipe({source, note_id, expected_version?})— persist Recipe to a vault note (facet-scoped — Description + Python + frontmatter survive byte-for-byte). Bumpsrecipe_versionin the note's frontmatter. Optimistic-concurrency viaexpected_version; version-conflict returnsisError:truewith expected + current numbers.
Resources
forge-note:///{domain}/{name}— library note content.forge-artifact:///{run_id}/{artifact_name}— on-demand binary fetch for run artifacts. Text mimes return viatext; binaries via base64blob.forge-recipe:///{note_id}/v{n}— Recipe body at a specificrecipe_version(git-tracked vaults only; returns "history unavailable" text otherwise).
Auth
forge-mcp does NOT validate tokens itself — forge-transpile is the source of truth (guarded by FORGE_TRANSPILE_SECRET). Each request's Authorization: Bearer <token> header is forwarded verbatim; a 401 or 403 from forge-transpile surfaces as isError: true with an actionable message the agent can read (drain CW-MCP-1-B).
Rotation is zero-downtime on the forge-mcp side: change FORGE_TRANSPILE_SECRET on forge-transpile, update your MCP client's header, done. Old tokens fail on the next request with a clean rejection message.
Related repos
- forge — the E-- parser + transpiler + core music library. forge-mcp vendors a snapshot of
forge/recipe/per the CW-MCP-2-A architecture; drift is caught byscripts/check-recipe-drift.shin the forge-transpile repo. - forge-transpile — the FastAPI service exposing
/compile//run//catalogetc. that forge-mcp's tools proxy for the transpile + sandboxed-run paths. Vault reads + commits are LOCAL and don't hit forge-transpile. - forge-client-obsidian — the Obsidian plugin end of the same authoring loop. forge-mcp writes to the SAME vault the plugin reads/renders; both share the note-file format.
Forge MCP questions
How do I add Forge MCP to Claude Code?
Run claude mcp add --env 'FORGE_MCP_BEARER=<YOUR_FORGE_MCP_BEARER>' forge-mcp -- uvx forge-recipe-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Forge MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Forge MCP provide?
It exposes 6 tools, including forge_read_note_catalog, forge_read_notes_in_vault, forge_compile_recipe, forge_run_recipe, forge_get_run_result.
How does authentication work?
The server forwards the Authorization Bearer token to the forge-transpile service, which acts as the source of truth for validation.