Installation

npm install
npm run build

Usage

With Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "terminal": {
      "command": "node",
      "args": ["/absolute/path/to/terminal-mcp-server/dist/index.js"],
      "env": {
        "TERMINAL_CWD": "/your/starting/directory"
      }
    }
  }
}

With Claude Code

claude mcp add terminal node /absolute/path/to/terminal-mcp-server/dist/index.js

Configuration

Tool Reference

terminal_execute

Runs a shell command in the current working directory. stdout/stderr are omitted from the response when empty. Output is truncated at 50,000 characters (head + tail) to keep responses manageable. Returns exit_code, and optionally stdout, stderr, and timed_out.

terminal_read_file

Reads a file as UTF-8 text, optionally restricted to a line range (1-based, inclusive). When no range is provided, returns the first 100 lines. Returns content, total_lines, size_bytes, and range (only when a partial read is requested).

terminal_write_file

Writes UTF-8 text to a file, creating it and any missing parent directories as needed. Returns bytes_written.

terminal_edit_file

Applies one or more find-and-replace operations to a file in order. Each old_str must appear exactly once. Returns edits_applied, and optionally the final file content.

terminal_list_dir

Lists entries in a directory with name, type (file, dir, symlink, other), size, and modified timestamp. Defaults to the current working directory.

terminal_mkdir

Creates a directory including any missing parents. Succeeds silently if the directory already exists.

terminal_delete

Deletes a file or directory. Directories are removed recursively by default.

terminal_copy

Copies a file or directory to a destination. If the destination is an existing directory, the source is copied inside it.

terminal_move

Moves or renames a file or directory. If the destination is an existing directory, the source is moved inside it. Falls back to copy + delete for cross-device moves.

terminal_search_files

Recursively searches for files and/or directories by name substring. Returns path, type, size, and modified for each match. Results are capped at max_results and a capped: true flag is included when the limit is hit.

terminal_env

Returns environment variables for the process. Sensitive variable names (SECRET, PASSWORD, TOKEN, KEY, CREDENTIAL) are masked to *** unless SHOW_SECRETS=1.

Safety

By default the server blocks patterns that could cause irreversible system damage:

• rm -rf / and similar root-wipe commands
• Disk format commands (mkfs, dd targeting /dev/sd* or /dev/hd*)
• Fork bombs
• System shutdown / reboot / halt (shutdown, reboot, halt, init 0)

Set ALLOW_DANGEROUS=1 to remove these guards (not recommended in production).

Sensitive environment variables (names containing SECRET, PASSWORD, TOKEN, KEY, or CREDENTIAL) are automatically masked in terminal_env output unless SHOW_SECRETS=1 is set.

Development

# Build TypeScript
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js