terminal-mcp-server

An MCP (Model Context Protocol) server that gives AI assistants full terminal access — execute commands, read/write/edit files, navigate the filesystem, manage directories, and inspect environment variables.

---

Features

Tool	Description
terminal_execute	Run any shell command with configurable timeout and env vars
terminal_cd	Change the working directory (persists across calls)
terminal_pwd	Show the current working directory
terminal_read_file	Read file contents by line range (1-based, inclusive); defaults to the first 100 lines
terminal_write_file	Write or append UTF-8 text to a file (creates parent dirs automatically)
terminal_edit_file	Apply ordered find-and-replace operations to a file; supports dry-run and preview
terminal_list_dir	List directory entries with name, type, size, and last-modified time
terminal_mkdir	Create a directory including any missing parents (idempotent)
terminal_delete	Delete a file or directory (recursive by default)
terminal_copy	Copy a file or directory to a new location
terminal_move	Move or rename a file or directory (handles cross-device moves)
terminal_search_files	Recursively search for files/directories by name with include/exclude filters
terminal_env	Inspect environment variables with optional name filter (sensitive values masked by default)

---

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

Environment Variable	Default	Description
TERMINAL_CWD	process.cwd()	Starting working directory
ALLOW_DANGEROUS	0	Set to 1 to disable safety blocks (⚠️ use with caution)
SHOW_SECRETS	0	Set to 1 to unmask sensitive env vars in terminal_env

---

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.

Parameter	Type	Default	Description
command	string	—	Shell command to execute
timeout_ms	integer	30000	Timeout in ms (1,000–300,000)
env	object	—	Extra env vars for this invocation

---

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).

Parameter	Type	Default	Description
path	string	—	File path (absolute, relative to cwd, or ~)
start_line	integer	1	First line to return
end_line	integer	start_line + 99	Last line to return (inclusive)

---

terminal_write_file

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

Parameter	Type	Default	Description
path	string	—	File path to write
content	string	—	Content to write
append	boolean	false	Append instead of overwrite

---

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.

Parameter	Type	Default	Description
path	string	—	Path to the file to edit
edits	array	—	Ordered list of { old_str, new_str } objects
dry_run	boolean	false	Preview changes without writing to disk
show_result	boolean	false	Include the full resulting content in the response

---

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.

Parameter	Type	Default	Description
path	string	cwd	Directory to list
show_hidden	boolean	false	Include dot-files

---

terminal_mkdir

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

Parameter	Type	Description
path	string	Directory path to create

---

terminal_delete

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

Parameter	Type	Default	Description
path	string	—	Path to delete
recursive	boolean	true	Remove directory contents recursively

---

terminal_copy

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

Parameter	Type	Default	Description
source	string	—	Source path
destination	string	—	Destination path or directory
overwrite	boolean	false	Overwrite if destination already exists

---

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.

Parameter	Type	Default	Description
source	string	—	Source path
destination	string	—	Destination path or directory
overwrite	boolean	false	Overwrite if destination already exists

---

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.

Parameter	Type	Default	Description
path	string	cwd	Root directory to search
include_pattern	string	—	Include entries whose name contains this (case-insensitive)
exclude_pattern	string	—	Exclude entries whose name contains this (case-insensitive)
type	file | directory | any	any	Filter by entry type
max_depth	integer	10	Maximum recursion depth (1–50)
max_results	integer	200	Maximum results to return (1–1,000)
show_hidden	boolean	false	Include hidden entries (starting with .)

---

terminal_env

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

Parameter	Type	Description
filter	string	Case-insensitive substring filter on variable names

---

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