Forge MCP Server

<h1 align="center">Forge</h1>

Terminal MCP server for AI coding agents. Spawn, manage, and monitor real PTY sessions via the Model Context Protocol.

<strong>forgemcp.dev</strong>

---

Why

AI coding agents (Claude Code, Codex, etc.) typically run one command at a time. Forge gives them persistent terminals — run your React frontend, Java API, and Postgres migrations in parallel, monitor all three, and only read what changed. Full-stack work without the bottleneck.

Works with any MCP-compatible client — Claude Code, Codex, or your own agent.

Key differentiators:

• Real PTY via node-pty (same lib as VS Code terminal) — interactive programs, colors, TUI apps all work
• Incremental reads — ring buffer with per-consumer cursors means each read_terminal only returns NEW output, saving context window tokens
• Clean screen reads — @xterm/headless renders the terminal server-side, so read_screen returns exactly what a human would see (no ANSI escape codes)
• Multi-agent orchestration — spawn Claude and Codex sub-agents, session groups, output multiplexing, event subscriptions, and templates for managing multiple concurrent sessions
• Web dashboard — real-time Preact-based browser UI to watch what your agents are doing across all terminals, browse past chat sessions, and monitor activity
• Zero config — single npx command or HTTP MCP endpoint

Quick Start

1. Add to Your Agent

<details open> <summary><strong>Claude Code</strong></summary>

# Basic (stdio)
claude mcp add forge -- npx forge-terminal-mcp

# With web dashboard
claude mcp add forge -- npx forge-terminal-mcp --dashboard --port 3141

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "forge": {
      "command": "npx",
      "args": ["forge-terminal-mcp", "--dashboard", "--port", "3141"]
    }
  }
}

</details> <details> <summary><strong>Codex</strong></summary>

# Add Forge as HTTP MCP server
codex mcp add forge --url http://127.0.0.1:3141/mcp

# Verify
codex mcp list
codex mcp get forge

Codex stores this in ~/.codex/config.toml:

[mcp_servers.forge]
url = "http://127.0.0.1:3141/mcp"

</details> <details> <summary><strong>HTTP MCP (any client)</strong></summary>

Start the daemon (choose one launch mode), then point any MCP client at the HTTP endpoint:

# If forge is on PATH (global install or npm link)
forge start -d

# From this repo (local clone)
node dist/cli.js start -d

# Without install (published package)
npx forge-terminal-mcp start -d

{
  "mcpServers": {
    "forge": {
      "type": "http",
      "url": "http://127.0.0.1:3141/mcp"
    }
  }
}

</details>

Restart your agent and Forge tools are available.

Important: Codex and Claude Code load MCP servers at process start. If you add/remove servers, restart the current agent session.

2. Smoke Test (60s)

# Codex MCP registration
codex mcp list
codex mcp get forge

# Forge daemon status
node dist/cli.js status

Expected:

• codex mcp list shows forge as enabled
• node dist/cli.js status reports running and http://127.0.0.1:3141

Troubleshooting

Symptom	Fix
forge: command not found	Use node dist/cli.js ... from the repo root, or npx forge-terminal-mcp ....
No MCP servers configured yet in Codex	Run codex mcp add forge --url http://127.0.0.1:3141/mcp, then restart Codex.
listen EPERM ... 127.0.0.1:3141	Run Forge in an environment that allows local port binding, or use a different port with --port and update the MCP URL to match.
A message appears typed but agent does not answer	The input may be queued; press Enter (or use submit=true when writing programmatically).
MCP server is configured but tools do not appear	Restart the curre