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.

⚠️ Read this first

This connects Claude to a real terminal on your computer. Claude will be able to run whatever commands it decides to run, within the safety limits below. Only install this if you're comfortable with that level of access — treat it like handing someone a terminal, not like a sandboxed toy. See SECURITY.md for the full threat model.

Built-in guardrails (not a full security boundary, just a basic net):

• Refuses a short list of obviously destructive commands (rm -rf /, fork bombs, mkfs, etc.)
• Anything at or under BASE_DIR (defaults to your home directory) always works with no friction
• Any path outside BASE_DIR needs a one-time permission grant before it's touched — see Directory permissions below
• 30-second default timeout per command (configurable per call)

Project structure

terminal-mcp/
├── server.py               # the MCP server (tools: run_command, list_directory, read_file,
│                            #   write_file, get_cwd, grant/revoke/list_directory_permission(s))
├── tests/
│   └── test_server.py       # pytest suite (risky-command regex, path resolution, permissions, tool behavior)
├── pyproject.toml           # deps (mcp[cli]) + dev extras (pytest, ruff) + packaging metadata + ruff config
├── install.sh               # one-shot installer (uv + venv + deps + Claude Desktop config, cross-platform)
├── uninstall.sh             # removes the "terminal" entry from Claude Desktop's config
├── .github/workflows/ci.yml # runs ruff + pytest on push/PR
├── .gitignore
├── LICENSE                  # MIT
├── SECURITY.md              # threat model & guardrail limitations
├── 00_change.md             # AI-assisted change log (what changed, why, by whom)
└── README.md

Quick install (recommended)

From inside this folder:

cd terminal-mcp
./install.sh

The script will:

1. Detect your OS (macOS / Linux / Windows-git-bash)
2. Make sure uv is installed (offering to install it for you if it isn't), then create a venv/ here (if it doesn't exist yet) and install dependencies from pyproject.toml
3. Ask you for the base directory the terminal tool should be scoped to (defaults to your home directory — press Enter to accept)
4. Auto-detect this folder's absolute path and write the correct command and args into your Claude Desktop config
5. Back up your existing claude_desktop_config.json before touching it, and merge in the terminal entry (other MCP servers you already have configured are left untouched)

Then just restart Claude Desktop.

To remove it later:

./uninstall.sh

This removes only the terminal entry from the config (backing it up first) — it doesn't touch this repo or the venv.

Manual install

If you'd rather do it by hand:

1. Install dependencies

Requires uv (curl -LsSf https://astral.sh/uv/install.sh | sh):

cd terminal-mcp
uv venv venv
uv pip install --python venv/bin/python .        # Windows: venv\Scripts\python.exe

2. Test it locally (optional but recommended)

The mcp package ships a dev inspector so you can try tools before wiring it into Claude Desktop:

mcp dev server.py

This opens a local web UI where you can call run_command, list_directory, etc. and see the results.

3. Connect it to Claude Desktop

Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add (or merge in) this entry, using the absolute path to your server.py and to the Python interpreter inside the venv you just created:

{
  "mcpServers": {
    "terminal": {
      "command": "/absolute/path/to/terminal-mcp/venv/bin/python",
      "args": ["/absolute/path/to/terminal-mcp/server.py"],
      "env": {
        "TERMINAL_MCP_BASE_DIR": "/absolute/path/to/wherever/you/want/it/scoped"
      }
    }
  }
}

On Windows, command would point at ...\\terminal-mcp\\venv\\Scripts\\python.exe.

4. Restart Claude Desktop

You should see a 🔌 / tools icon indicating the terminal server is connected, with tools: run_command, list_directory, read_file, write_file, get_cwd, grant_directory_permission, revoke_directory_permission, list_directory_permissions.

Directory permissions

Anything at or under BASE_DIR always works with no friction, same as before. Any path outside BASE_DIR — say you're scoped to a project folder but ask Claude to look at ~/Downloads — now needs a one-time permission grant before the server will touch it. Once granted, it's remembered across restarts (stored in ~/.terminal-mcp/permissions.json by default, or wherever TERMINAL_MCP_PERMISSIONS_FILE points) and never asked again.

When Claude hits a path with no standing permission, it'll ask you to pick a scope:

• This directory only — just that directory, plus files directly inside it. Subdirectories still need their own grant. Example: allowing /Users/dha/Downloads this way does not also allow /Users/dha/Downloads/dwe.
• This directory and all subdirectories — the directory plus everything nested beneath it, at any depth. Example: allowing /Users/dha/Downloads this way also allows /Users/dha/Downloads/dwe, /Users/dha/Downloads/dwe/test, etc.

Ask Claude things like:

• "List what directories are allowed" / "terminal list allowed" → shows every granted path and its scope
• "Revoke access to ~/Downloads" → removes that entry; the next request there will prompt again

Try it

Ask Claude something like:

• "List the files in my current project folder"
• "Run git status in ~/projects/my-app"
• "Read the contents of config.yaml and summarize it"
• "Create a file called notes.txt with today's todo list"
• "Always allow ~/Downloads and its subdirectories"

Development

uv pip install --python venv/bin/python ".[dev]"
ruff check .        # lint
pytest -v           # run tests

CI (.github/workflows/ci.yml) runs both on every push/PR to main across Python 3.10–3.12.

Customizing

• Scope it tighter: set TERMINAL_MCP_BASE_DIR to a specific project folder instead of your home directory, so everything else requires an explicit permission grant (see Directory permissions).
• Move the permissions store: set TERMINAL_MCP_PERMISSIONS_FILE to change where granted permissions are persisted (default ~/.terminal-mcp/permissions.json).
• Add more guardrails: extend RISKY_PATTERNS in server.py for any other commands you never want run automatically.
• Add more tools: the pattern is @mcp.tool() decorating a function with a docstring — Claude reads the docstring to know when/how to call it. You could add things like git_diff, run_tests, curl, etc. as dedicated tools with tighter guardrails than raw run_command.

Using with Claude Code instead

If you're using Claude Code rather than Claude Desktop, you likely don't need this at all — Claude Code already has built-in terminal access. This server is most useful for Claude Desktop or other MCP clients that don't have a terminal tool of their own.

Change log

See 00_change.md for a running log of AI-assisted changes to this repo — what changed, why, and by which assistant.