Skip to main content
Glama
Sign In
termcp

termcp

by dbalchunas2-pixel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

termcp

A local terminal MCP server for AI agents. stdio-based, zero-config, just run commands.

termcp gives any MCP-compatible AI agent (Claude, etc.) a full terminal on your machine - shell commands, file operations, background processes, search, and stateful sessions - all through the standard Model Context Protocol over stdio. No server to deploy, no tokens to manage, no cloud.

Quick start

git clone https://github.com/dbalchunas2-pixel/termcp.git
cd termcp
npm install
npm run build

Add to your MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "termcp": {
      "command": "node",
      "args": ["/path/to/termcp/dist/index.js"]
    }
  }
}

That's it. Your AI agent now has a terminal.

Related MCP server: mcp-interactive-terminal

Tools

Tool

Description

run_command

Execute a shell command. Supports stdin and tmux sessions.

run_sequence

Execute multiple commands in sequence with variable capture ($PREV, $STEP{n}).

read_file

Read a file.

write_file

Write a file. Creates parent directories.

list_files

List files and directories.

search_files

Search file contents (ripgrep or grep).

get_environment

Get OS, installed tools, and disk info.

get_audit_log

Get the audit log with filtering.

get_server_info

Get version, uptime, workspace, active processes.

start_process

Start a long-running background process.

poll_output

Poll output from a background process.

kill_process

Kill a background process.

create_session

Create a stateful tmux session (persists cwd/env).

destroy_session

Kill a tmux session.

read_output

Read output from a byte offset (for truncated output).

Configuration

All config is via environment variables. All optional.

Variable

Default

Description

TERMCP_WORKSPACE

$HOME

Root directory for file operations.

MAX_TIMEOUT_MS

300000

Maximum command timeout in ms.

DEFAULT_TIMEOUT_MS

30000

Default command timeout in ms.

MAX_OUTPUT_CHUNK

50000

Output chunk size before truncation.

Denylist

termcp ships with a configurable denylist for accident protection (not a security boundary). Create a denylist.json file:

{
  "patterns": ["rm -rf /", "mkfs", "dd if=", "shutdown", "reboot"]
}

Place it in the project root, ~/.termcp/denylist.json, or set TERMCP_WORKSPACE to its directory. Patterns use simple substring matching.

Audit log

termcp maintains a durable JSONL audit log at ~/.termcp/audit.jsonl. Every command is logged with timestamp, tool, input, exit code, and duration. Secrets are redacted at write time (API keys, Bearer tokens, password assignments).

Requirements

  • Node.js 18+

  • tmux (optional, for create_session/destroy_session tools)

  • ripgrep (optional, for faster search_files)

License

MIT

Available Tools

15 tools
create_sessionA

Create a stateful tmux session with persistent cwd and environment.

Inputs: cwd.

destroy_sessionC

Kill a tmux session.

Inputs: session_id (required).

get_audit_logB

Get the audit log of commands executed. Supports filtering.

Inputs: tool, count, since.

get_environmentA

Get info about the local environment: OS, installed tools, disk usage.

Inputs: no named parameters.

get_server_infoA

Get server info: version, uptime, workspace, active processes.

Inputs: no named parameters.

kill_processC

Kill a background process by process_id.

Inputs: process_id (required), signal.

list_filesB

List files and directories in a path.

Inputs: path.

poll_outputC

Poll output from a background process.

Inputs: process_id (required), since.

read_fileC

Read the contents of a text file.

Inputs: path (required).

read_outputA

Read output from a specific byte offset. Used for truncated output.

Inputs: offset, process_id.

run_commandB

Execute a shell command locally. Returns stdout, stderr, and exit code.

Inputs: command (required), cwd, stdin, session_id, +1 more.

run_sequenceB

Execute multiple shell commands in sequence. Supports variable capture ($PREV, $STEP{n}).

Inputs: commands (required), cwd, timeout_ms, stop_on_error.

search_filesB

Search for a pattern in files. Uses ripgrep if available, falls back to grep.

Inputs: pattern (required), glob, path.

start_processA

Start a long-running background process. Returns process_id and pid.

Inputs: command (required), cwd, env.

write_fileA

Write content to a file. Creates parent directories if needed.

Inputs: path (required), content (required), append.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (file ops vs command execution vs process lifecycle vs sessions). Some overlap exists between run_command and run_sequence, and between poll_output and read_output, but descriptions provide enough differentiation to avoid major confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (run_command, read_file, start_process, etc.). No mixing of conventions or vague verbs.

    Tool Count4/5

    15 tools is within the reasonable range for a terminal/shell server covering command execution, file operations, process management, and sessions. Slightly at the upper bound, but each tool appears to earn its place.

    Completeness4/5

    Core workflows are covered: sync/async command execution, file read/write/list/search, process lifecycle, session management, and environment info. Minor gaps exist such as no file delete/move/copy operations and no explicit way to send input to a running process or session.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • terminal-mcp

      ParthKapoor-dev
      F
      license
      Not graded
      quality
      Not graded
      maintenance
      A secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.
      -

    • Unterm

      zhitongblog
      F
      license
      Not graded
      quality
      B
      maintenance
      The terminal AI agents can drive: a cross-platform desktop terminal (macOS/Linux/Windows, MIT) that runs a local MCP server. Spawn tabs/panes, run commands with structured output, read screens and full scrollback, take scrolling screenshots, record sessions with secret redaction, switch identity profiles. Auto-registers with Claude Code / Codex / Gemini CLI on install.
      17
      -

    • termcp

      open-mcp-ai
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to interact with real terminal sessions across local and remote hosts, driving multi-turn interactive programs like TUIs, REPLs, and SSH prompts through MCP.
      67
      MIT

    Appeared in Searches