Terminal MCP Server

Gives Claude Desktop (or any MCP client) the ability to run shell commands, read/write files, and list directories on your machine -- plus 13 operation- based tools covering git, archives, search, process/system inspection, SQLite, text processing, and more (see Available Tools below). These 13 replace what used to be 85 separate narrow tools, so far less tool-schema context gets loaded into every conversation turn without losing any capability -- each one just takes an operation argument.

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/dha-aa/terminal-mcp/main/install.sh | bash

Custom Install Directory

curl -fsSL https://raw.githubusercontent.com/dha-aa/terminal-mcp/main/install.sh | bash -s -- --dir ~/my-terminal-mcp

Manual Install

git clone https://github.com/dha-aa/terminal-mcp.git
cd terminal-mcp
./install.sh

Related MCP server: Local Dev Bridge MCP

Uninstall

# If using default install location
~/.terminal-mcp/scripts/uninstall.sh

# Or your custom install directory
/path/to/terminal-mcp/scripts/uninstall.sh

⚠️ Security Note

This connects Claude to a real terminal on your computer. Claude will be able to run whatever commands it decides to run, within the base directory you specify. Only install this if you're comfortable with that level of access.

Available Tools

Core Tools:

• run_command - Execute shell commands (own process group, output truncation, retries, env vars)

• list_directory - List directory contents

• read_file - Read entire file contents

• read_file_lines - Read specific line ranges (token-efficient)

• write_file - Write/overwrite files

• replace_in_file - Replace text without full read (token-efficient)

• search_in_file - Search for patterns in files, literal or regex (token-efficient)

• get_cwd - Get current working directory

File/Directory Management:

• make_directory - Create a directory (mkdir -p style)

• delete_path - Delete a file or directory (always confirm-gated, previews first)

• move_path - Move/rename a file or directory

• copy_path - Copy a file or directory (recursive for directories)

• file_info - Stat a path: size, kind, modified time, permissions

Batch/Async Tools:

• run_task - Run multiple commands in sequence

• run_command_async - Run commands in background

• get_job_status - Check background job status

• list_jobs - List all background jobs

• cancel_job - Cancel running jobs (actually terminates the process tree, SIGTERM then SIGKILL)

Permission Tools:

• grant_directory_permission - Grant directory access

• revoke_directory_permission - Revoke directory access

• list_directory_permissions - List granted permissions

Consolidated Tools (13 tools, each takes an operation argument):

These replace what used to be 85 separate tools. Every underlying function (git_status, sqlite_query, tail_file, etc.) still exists in server.py with identical behavior and confirm-gating -- only the individual tool registration was merged into a dispatcher, so nothing lost capability.

• fs_search - glob / grep / find / regex / list_recursive — find files by name, search file contents across a tree, filter by size/mtime, regex-extract matches, or list a directory tree recursively.

• fs_inspect - stats / type / checksum / compare / dir_size / dir_diff / dir_snapshot — line/word/char counts, file-type detection, md5/sha1/sha256 hashing, unified diff between two files, directory size, directory-tree diff, and a poll-based directory manifest (no live filesystem watch exists in this environment; snapshot it twice and diff yourself).

• fs_read_ext - tail / head / stream / binary — last/first N lines, a byte-offset chunk of a large file, or read a binary file as base64.

• fs_write_ext - create / append / truncate / write_binary / touch / chmod / symlink / rmdir_empty — new file (fails if exists), append text, truncate/empty a file (confirm-gated), write a base64 payload as raw bytes, touch, change permission bits (confirm-gated), create a symlink, remove an empty directory.

• fs_edit - insert_line / delete_line / replace_line / apply_patch / diff / search_replace / sort / unique — precise single-line edits (confirm-gated), apply a unified diff (confirm-gated, minimal applier — context-line matching, not a full patch(1) replacement), generate a diff between two files, bulk find/replace across a tree (dry-run by default), sort or dedupe a file's lines (confirm-gated when writing in place).

• archive - zip_create / zip_extract / tar_create / tar_extract / gzip_compress / gzip_decomp / list_contents — zip/tar create & extract (path-traversal / "zip-slip" protected), gzip a single file, list archive contents without extracting.

• git - status / diff / log / add / commit / push / pull / branch_list / branch_create / checkout / stash / stash_pop / blame / clone / merge / rebase / remote_list / tag — push, merge, rebase, and stash_pop are confirm-gated (publish to a remote, rewrite history, or discard a stash).

• process - list / kill / info / port_check — list running processes, terminate a PID (confirm-gated), CPU/mem for a PID, check if a TCP port is in use.

• system - info / env_get / env_list / which / ping / http_check — OS/CPU/memory/disk summary, read env vars, resolve a binary on PATH, ping a host, HEAD-style URL status/header check.

• cron - list / add / remove / schedule_delayed — manage the user's crontab (confirm-gated), or run a command after a delay in the background.

• package - pip_install / npm_install / list / check_version — install a package, list installed pip/npm packages, check an installed package's version.

• data - sqlite_query / sqlite_dump / sqlite_restore / json_query / csv_read / csv_write — SQL against a SQLite file (writes/DDL confirm-gated), dump/restore a SQLite db to/from .sql (sqlite_restore confirm-gated), read JSON with a dotted key path, read/write CSV as JSON rows.

• security - encrypt / decrypt / hash / verify_checksum — AES-256-CBC file encryption via openssl (password piped via stdin, never a CLI argument, so it isn't visible in ps output), hash a string, compare a file's hash against an expected value.

Note: apply_patch is a minimal unified-diff applier, not a full patch(1) replacement. fs_inspect dir_snapshot is a poll-based filesystem-watch substitute -- no live watch exists in this environment.