mcp-forger 1.0.4

Convert any application into an MCP server — with AI assistance. CLI + Claude Desktop plugin.

🔨 MCP Forger

Your software becomes an AI coworker.

MCP Forger turns any app, API, repo, or codebase into an AI coworker that Claude, Codex, and other MCP clients can use directly. Give it your backend. It analyzes it, generates an MCP server, tests it, and lets Claude operate your software through natural language. Convert any application into an MCP (Model Context Protocol) server — with AI assistance.

✨ Features

Category	Highlights
Source ingestion	Local folder (mnt/) · OpenAPI/Swagger URL (under testing) · GitHub repo (under testing) · Live URL probing (under testing) · File upload (under testing) · Manual description (under testing)
AI agent	Multi-LLM (Gemini · Anthropic · OpenAI · local HuggingFace) · per-project chat · clarification Q&A loop
Code generation	Python FastMCP (stable) · Node.js / Go / Generic (under development & testing) · LLM polish pass · security audit · auto-generated .env, configure_claude.sh & configure_claude.ps1
Versioning	Snapshot on every generation · one-click rollback · optional git commits
Testing	AI-generated pytest cases · in-container runner · full test history
Dashboard	Real-time logs · 6-tab project view · editable .env config from the browser
Integrations	Claude Desktop · Claude Code · Codex · forge CLI

---

🗺️ Two Ways to Use MCP Forger

Method	Best for
Web Dashboard	Visual workflow — point & click, no code
forge CLI + Claude Desktop	AI-driven workflow from your terminal or Claude chat

Both require MCP Forger running in Docker first — see Step 1 below.

---

Step 1 — Run MCP Forger (Docker)

Required for everything — the dashboard, CLI, and Claude Desktop all connect to this Docker instance.

Prerequisites

• Docker Desktop installed and running
• At least one LLM API key or an NVIDIA GPU for local mode

1.1 — Clone & configure

git clone https://github.com/coderXcode/mcp-forge.git
cd mcp-forge
cp .env.example .env

Open .env and set at minimum:

LLM_PROVIDER=gemini          # or: anthropic | openai | local
GEMINI_API_KEY=your-key-here

# This token authenticates the CLI and Claude Desktop — change it to something secret
MCP_AUTH_TOKEN=change-me-to-something-secret

Free option: Gemini has a free tier at aistudio.google.com — no credit card needed.

No API key? Run locally instead: Set LLM_PROVIDER=local and leave the API key fields empty. On macOS run bash scripts/start_model_server.sh after Docker starts. On Linux with NVIDIA GPU the model loads inside Docker automatically. See Local Model for details.

1.2 — macOS / Linux — disable the NVIDIA GPU block first

Skip this if you are on Windows with an NVIDIA GPU.

The default docker-compose.yml includes an NVIDIA GPU reservation that causes Docker to fail on macOS (and any machine without an NVIDIA GPU). Open docker-compose.yml and comment out the deploy: block under the app: service:

    # ── GPU (NVIDIA) — uncomment if on Linux with NVIDIA GPU ────────────────
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]

It should already be commented out if you cloned the latest version. If you see it uncommented, add # in front of each of those lines.

If you also want to change the MCP server port (e.g. port 8001 is already in use), edit MCP_SERVER_PORT in .env before starting:

MCP_SERVER_PORT=8002   # change to any free port

1.3 — Start

docker compose up -d

Service	URL	Purpose
🌐 Dashboard	http://localhost:8000	Web UI — full visual workflow
🔌 MCP endpoint	http://localhost:8002/sse	Used by Claude Desktop / Claude Code (default port)

1.4 — Verify it's running

# Should return [] (empty list — that's fine)
curl http://localhost:8000/api/projects/

✅ MCP Forger is now online. Keep Docker running whenever you use the CLI or Claude Desktop.

---

Step 2A — Use the Web Dashboard

Visit http://localhost:8000 → click + New Project → follow the UI.

No further setup needed.

---

Step 2B — Use the forge CLI

Install

pip install mcp-forger
# or: pipx install mcp-forger  (isolated, recommended)

Connect the CLI to your running MCP Forger instance

Do this once — it saves your connection details locally.

forge connect --url http://localhost:8000 --token YOUR_MCP_AUTH_TOKEN

Get your token with:

# macOS / Linux
grep -m1 '^MCP_AUTH_TOKEN=' .env | cut -d= -f2
# Windows (PowerShell)
(Get-Content .env | Where-Object { $_ -match '^MCP_AUTH_TOKEN=' }) -replace '^MCP_AUTH_TOKEN=',''

Verify

forge status
# Should list your projects (empty at first — that's fine)

Create and convert your first project

# Recommended: from a local folder
# 1. Copy your project into mnt/  (e.g. mnt/my-api/)
# 2. Create the project on the dashboard or via Claude Desktop
# 3. Trigger analysis
forge analyze 1

# Check what's happening
forge logs 1 --tail 20

# Generate the MCP server (Python FastMCP is the stable option)
forge generate 1 --lang python_fastmcp

# Run AI-generated tests
forge test 1

# Chat with the AI agent
forge chat 1 "review all endpoints and ask me anything unclear"

Install the Claude Desktop plugin (one command)

forge plugin install
# Then fully quit + reopen Claude Desktop

This writes claude_desktop_config.json automatically — no manual editing.

All CLI commands

forge connect   --url <url> --token <token>    # save connection (run once)
forge status                                    # list all projects
forge analyze   <project_id>                    # trigger analysis
forge generate  <project_id> --lang <lang>      # generate MCP server
forge chat      <project_id> "<message>"        # chat with AI agent
forge logs      <project_id> --tail 50          # stream live logs
forge test      <project_id>                    # run AI-generated tests
forge plugin    install                         # write claude_desktop_config.json
forge plugin    status                          # verify Claude Desktop config

---

Step 2C — Use Claude Desktop

Claude Desktop lets you control MCP Forger entirely through natural language.

Install the plugin

Windows (PowerShell):

.\scripts\install_claude_plugin.ps1

macOS / Linux:

bash scripts/install_claude_plugin.sh

Or if you have the CLI installed:

forge plugin install

Then fully quit and reopen Claude Desktop (right-click system tray → Quit).

Go to Settings → Developer — you should see mcp-forge with a 🟢 green dot.

Example prompts

Recommended — local folder (most reliable):

Create a new MCP Forge project called "my-api",
source type local_folder, path /mnt/my-api

OpenAPI/Swagger URL (under testing):

Create a new MCP Forge project called "petstore" from
https://petstore3.swagger.io/api/v3/openapi.json

Generate the MCP server for project 1 in Python FastMCP

Run tests for project 1 and show me the results

Chat with the forge agent for project 1:
"Add rate limiting to all tools"

Language note: Only Python FastMCP is stable. Node.js, Go, and other language targets are under development and testing.

---

Step 2D — Use Claude Code

/plugin marketplace add coderXcode/mcp-forge
/plugin install mcp-forge@coderXcode-mcp-forge

Skills available:

/forge:analyze <project_id>
/forge:generate <project_id>
/forge:chat <project_id> <message>
/forge:status
/forge:test <project_id>
/forge:rollback <project_id> <version>

---

Step 3 — Connect Your Generated MCP Server to Claude Desktop

Understanding the two plugins

After this step you will have two separate plugins in Claude Desktop — they do different things:

Plugin	What it does	Installed by
mcp-forge	Lets Claude operate MCP Forge itself — create projects, generate code, run tests	forge plugin install (Step 2C)
your-project-name	Lets Claude call your actual app directly — the converted product	bash configure_claude.sh (this step)

They are completely independent. You can use either or both. The generated plugin (your-project-name) is the end product — it talks directly to your running app, with no dependency on MCP Forge once it's set up.

Important: The generated plugin needs your original app to be running. It doesn't start your app for you — it just gives Claude a way to talk to it. Make sure your app is running at the BASE_URL set in .env before asking Claude to use it.

Run the setup script

Open a terminal in the generated project folder and run:

macOS / Linux

bash configure_claude.sh

Windows (PowerShell)

.\configure_claude.ps1

The script does everything in one step:

1. Creates a Python virtual environment (.venv/)
2. Installs dependencies from requirements.txt
3. Finds the right claude_desktop_config.json for your OS
4. Safely merges a new mcpServers entry — existing entries are preserved
5. Prints restart instructions

Then fully quit and reopen Claude Desktop (system tray → Quit, not just close window). Your converted API appears as a new tool with a 🟢 green dot.

Non-standard port? Pass --base-url to override the default:

bash configure_claude.sh --base-url http://localhost:9000

The generated .env file also lets you set BASE_URL and API_TOKEN before running the script.

---

🖥️ Local Model (No API Key)

Run entirely offline with any HuggingFace model — no API key needed.

Linux with NVIDIA GPU

Set in .env (or via the dashboard Config page → select Local):

LLM_PROVIDER=local
LOCAL_MODEL=Qwen/Qwen2.5-Coder-14B-Instruct
LOCAL_MODEL_DEVICE=auto
LOCAL_MODEL_LOAD_IN_4BIT=true

docker compose up -d

macOS (Apple Silicon or Intel)

Docker cannot access the Mac GPU, so the model runs natively on the host instead. One command does everything (installs deps, creates a venv, starts the server):

bash scripts/start_model_server.sh

Wait until the terminal shows Listening on 0.0.0.0:8005, then go to the dashboard Config page and select Local — the app will proxy inference requests to the native server automatically. Model weights download once to ./cache/huggingface/ and are reused on every subsequent start.

The script auto-selects the best model for your RAM (7B for 16–32 GB, 14B for 36 GB+).

Model	RAM (unified)	Notes
Qwen/Qwen2.5-Coder-7B-Instruct	~16 GB	Recommended for most Macs
Qwen/Qwen2.5-Coder-14B-Instruct	~36 GB	Better quality, needs more RAM
Qwen/Qwen2.5-Coder-32B-Instruct	~64 GB	Best quality

Linux / NVIDIA — CPU-only fallback: set LOCAL_MODEL_LOAD_IN_4BIT=false and LOCAL_MODEL_DEVICE=cpu — slower but works.

---

⚙️ Key Configuration

All settings live in .env — also editable live from the dashboard Config page without restarting Docker. Switch LLM providers anytime: open Config, click Gemini / Anthropic / OpenAI / Local, enter your key, and click Save Changes.

Variable	Default	Description
LLM_PROVIDER	gemini	gemini | anthropic | openai | local
GEMINI_API_KEY	—	Google Gemini API key
ANTHROPIC_API_KEY	—	Anthropic Claude API key
OPENAI_API_KEY	—	OpenAI API key
MCP_AUTH_TOKEN	change-me	Auth token for CLI / Claude — change this
GITHUB_TOKEN	—	PAT for private GitHub repos
LOCAL_MODEL	Qwen/Qwen2.5-Coder-14B-Instruct	Any HuggingFace model ID
ENABLE_GIT_SNAPSHOTS	false	Auto-commit each snapshot to git
DEBUG	false	Verbose logs + uvicorn reload

---

🐳 Useful Docker Commands

docker compose up -d              # start
docker compose up -d --build      # rebuild after code changes
docker compose restart            # restart after .env changes
docker compose down -v            # stop + wipe database
docker logs mcp_forge_app -f      # app logs
docker logs mcp_forge_mcp -f      # MCP server logs

---

🔧 Troubleshooting

mcp-forge not showing in Claude Desktop (red dot / missing)

• Fully quit Claude Desktop (system tray → Quit, not just close)
• Re-run: forge plugin install or .\scripts\install_claude_plugin.ps1
• Validate JSON at jsonlint.com

"Connection refused" on port 8000 or 8001

docker ps                          # check containers are running
docker compose up -d               # start if not running
docker logs mcp_forge_app --tail 30

Wrong / expired auth token

# macOS / Linux
grep -m1 '^MCP_AUTH_TOKEN=' .env | cut -d= -f2
# Windows (PowerShell)
(Get-Content .env | Where-Object { $_ -match '^MCP_AUTH_TOKEN=' }) -replace '^MCP_AUTH_TOKEN=',''

forge connect --url http://localhost:8000 --token <new-token>
forge plugin install   # updates claude_desktop_config.json too

Reset the database

echo y | docker exec -i mcp_forge_app python clear_db.py

---

📖 Full Documentation

See user_manual.md for advanced configuration, Codex integration, local folder setup, architecture details, and more.

---

📝 License

MIT