Forge

What ferodrigop/forge MCP server does

The ferodrigop/forge MCP server exposes real terminal sessions through the Model Context Protocol. Each session runs in a pseudo-terminal, allowing interactive programs, colored output, and terminal user interfaces to operate as they would in a normal terminal. Agents can create sessions with commands, working directories, names, tags, dimensions, and buffer settings, then reuse the returned session IDs for later operations.

It supports both long-lived workflows and disposable commands. run_command creates a session, waits for the process to finish, returns its output, and cleans up automatically. Persistent sessions are suited to development servers, test watchers, shells, and other processes that need follow-up input.

How it works

The ferodrigop/forge MCP server keeps terminal output in a ring buffer and tracks read positions per consumer. read_terminal therefore returns output added since the previous read rather than repeatedly returning the complete buffer. read_screen instead returns the current viewport as rendered text without ANSI escape sequences. grep_terminal searches buffered output with a regular expression, while wait_for can block until a pattern appears or a process exits.

Sessions can be monitored individually or in batches with read_multiple, filtered by tags, and grouped for cleanup. Event subscriptions emit MCP logging notifications when a session exits or matches a pattern. Terminal input can be written as text or sent as control sequences such as Ctrl+C, arrow keys, Enter, and Tab. The server also reports uptime, version, session count, and memory usage through health_check.

Setup and configuration

Install the published package with a package manager that provides npx, then start the local daemon:

npx forge-terminal-mcp start -d

The documented HTTP endpoint is http://127.0.0.1:3141/mcp. Clients connect to that endpoint after the daemon starts. The README also documents global npm or Bun installation and a standalone install script. A dashboard can be enabled with --dashboard, and the listening port can be changed with --port; the MCP client URL must match the selected port.

The project requires Node.js 18 or newer when using its npm installation path. MCP clients load server configuration at process startup, so clients need to be restarted after adding or removing the server.

Tools and capabilities

The tool set covers:

• Creating, reviving, listing, resizing, writing to, and closing PTY sessions.
• Starting sessions from templates such as shell, Next.js development, Vite development, and npm test.
• Launching Claude Code, Codex, and Gemini CLI agents in interactive or one-shot modes.
• Running delegated tasks in one-shot or multi-turn interactive mode.
• Monitoring output with incremental reads, screen capture, regex searches, waits, and event subscriptions.
• Reviewing or clearing persisted Claude and Codex session history.
• Running a real-time browser dashboard for terminal activity and past chat sessions.

When launching an agent session, the working directory must be supplied explicitly. Claude Code sessions can use a worktree and branch for isolated Git work; one-shot modes require the relevant prompt where documented.

Limitations and notes

The material describes a local daemon and local HTTP MCP endpoint rather than a hosted service. It does not document authentication, remote hosting, or environment variables. Commands executed through terminal sessions depend on the tools and permissions available in the host environment. Interactive agent sessions remain alive for follow-up work, while one-shot execution exits after processing its prompt. Forge is MIT-licensed.

The ferodrigop/forge MCP server is intended for MCP-compatible clients, with setup examples for Claude Code, Codex, and Gemini CLI. Those clients must be restarted when their MCP configuration changes.