forge-mcp

Read-only MCP server that gives Claude Code structured knowledge about the Forge repository, including its templates, project structure, documentation, validation rules, doctor checks, and generated-project conventions.

Forge remains the authoritative application. forge-mcp reads Forge; it does not modify it.

v0.1.1 has no write tools.

Related MCP server: Codelens-MCP

Tools

Requirements

• Python 3.10+

• Forge repository at a known path

• FORGE_REPOSITORY_ROOT environment variable or --forge-root CLI argument

Installation

cd forge-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Usage

# Set the Forge root and run the server over stdio
FORGE_REPOSITORY_ROOT=/srv/workspaces/projects/portfolio/forge forge-mcp

# Or pass it explicitly
forge-mcp --forge-root /srv/workspaces/projects/portfolio/forge

# Version check
forge-mcp --version
python -m forge_mcp --version

Claude Code setup

See docs/claude-code-setup.md and examples/claude-code.mcp.json.

Development

python -m pytest -q
python -m ruff check src/ tests/

Document availability

get_forge_overview distinguishes between documents that are approved in the allowlist and documents that are currently present on disk:

• available_documents — approved identifiers whose files exist in the Forge repository right now

• unavailable_documents — approved identifiers configured in the allowlist but whose files are absent

Both fields are always present. Both are sorted alphabetically by identifier. The union of the two sets always equals the full approved-document allowlist.

read_forge_document accepts only approved identifiers. It returns a structured error with code DOCUMENT_NOT_FOUND when the identifier is unknown or the file is absent, and DOCUMENT_ERROR for other read failures (binary content, size limit, encoding). It never accepts arbitrary paths.

Security

forge-mcp is strictly read-only. See docs/security-boundary.md.

Separation

Forge is a separate repository and application. forge-mcp does not modify Forge. forge-mcp does not import Forge modules, execute Forge commands, or touch Forge's Git history.