Terminal MCP server for AI coding agents.
Forge
Terminal MCP server for AI coding agents. Spawn, manage, and monitor real PTY sessions via the Model Context Protocol.
forgemcp.dev
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_terminalonly returns NEW output, saving context window tokens - Clean screen reads —
@xterm/headlessrenders the terminal server-side, soread_screenreturns 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
npxcommand or HTTP MCP endpoint
Quick Start
1. Add to Your Agent
Claude Code
# 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"]
}
}
}
Codex
# 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"
HTTP MCP (any client)
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"
}
}
}
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 listshowsforgeas enablednode dist/cli.js statusreports running andhttp://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 |
Tools (2)
read_terminalReads new output from a terminal session using a ring buffer to save context window tokens.read_screenReturns a clean, human-readable view of the terminal screen without ANSI escape codes.Configuration
{"mcpServers": {"forge": {"command": "npx", "args": ["forge-terminal-mcp", "--dashboard", "--port", "3141"]}}}