# 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

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

### Custom Install Directory

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

### Manual Install

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

## Uninstall

```bash
# 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.