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

• File operations are scoped to BASE_DIR (defaults to your home directory) unless you pass an absolute path

• 30-second default timeout per command (configurable per call)

Related MCP server: Local Dev Bridge MCP

Project structure

terminal-mcp/
├── server.py               # the MCP server (tools: run_command, list_directory, read_file, write_file, get_cwd)
├── tests/
│   └── test_server.py       # pytest suite (risky-command regex, path resolution, 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.

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"

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 relative paths can't wander outside it.

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