Host Terminal MCP

An MCP server that lets AI assistants run terminal commands on your machine with permission controls. Built for Claude Desktop / Co-work and any MCP-compatible client.

How It Works

Claude Desktop spawns host-terminal-mcp as a child process and communicates over stdin/stdout using the MCP protocol. There is no network server involved — it's a local pipe.

Setup for Co-work

1. Install

Or with pip:

2. Configure Claude Desktop

Add the MCP server to your Claude Desktop config file:

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

Important: Claude Desktop runs with a minimal PATH (/usr/local/bin, /usr/bin, /bin, /usr/sbin, /sbin, /opt/homebrew/bin). If you installed with uv tool install or pip install --user, the binary is likely in ~/.local/bin/ which is not in Claude Desktop's PATH. Use the full absolute path to the binary to avoid "No such file or directory" errors.

Find your binary path:

Then use that path in the config:

To start in ask mode (recommended — prompts you before running unlisted commands):

Tip: If you installed globally to a system path (e.g. /usr/local/bin/host-terminal-mcp), you can use just "command": "host-terminal-mcp" without the full path.

3. Restart Claude Desktop

Quit and reopen Claude Desktop. It will automatically spawn the host-terminal-mcp process. You can verify it's running:

4. Use it

Open a Co-work session in Claude.ai (or use Claude Desktop directly) and ask:

• "List files in my home directory"

• "Show git status in ~/projects/myapp"

• "What's running on port 3000?"

• "Run the tests for this project"

Why This Tool

Terminal access with guard rails. Three permission modes let you choose the right level of access — a locked-down allowlist for read-only commands, an ask mode that prompts you for real-time approval using MCP elicitation, or an unrestricted mode for sandboxed environments.

Skills that teach the AI how to use the terminal. The plugin ships with skills — structured guides that Claude reads at runtime. A codebase explorer skill teaches project navigation patterns (directory structure, manifest detection, dependency tracing). A terminal workflows skill teaches safe shell execution (command chaining, error handling, process management). Claude doesn't just get access — it gets expertise.

Slash commands and connectors. Built-in commands like /shell, /git, and /permissions give you direct control. A connector system (~~terminal) lets other plugins reference terminal access without being tied to a specific MCP implementation — swap in SSH, Docker, or a cloud shell without changing your workflows.

Permission Modes

How ask Mode Works

When Claude tries to run a command not in the allow list, the server uses MCP elicitation to prompt you (the human) directly in the Claude Desktop UI:

• Approve — runs the command for this session

• Add to allowed list permanently — saves the command to your config file so you're never asked again

• Cancel/Decline — command is blocked

This is a real human-in-the-loop: Claude cannot approve commands on its own.

Note: Elicitation requires MCP client support. If your client doesn't support it, unlisted commands are rejected with a message telling you to add them to the config file.

Permission check order: blocked (always wins) > allowed > session-approved > mode decision

Default Allowed Commands

These commands (and their arguments) are allowed out of the box:

File listing & navigation: ls, ll, la, pwd, tree, find, locate, which, whereis, file

File viewing: cat, head, tail, less, more, bat, wc

Search: grep, rg, ag, ack, fzf

Git (read-only): git status, git log, git diff, git show, git branch, git remote, git tag, git stash list, git rev-parse, git config --get, git config --list, git blame, git shortlog, git describe

System info: uname, hostname, whoami, id, date, uptime, df, du, free, top -l 1, ps

Network (read-only): ping -c, curl -I, curl --head, dig, nslookup, host, ifconfig, ip addr, netstat, ss

Package managers (info only): npm list, npm ls, npm view, npm show, npm outdated, pip list, pip show, pip freeze, brew list, brew info, apt list, dpkg -l

Dev tool versions: python --version, python3 --version, node --version, npm --version, cargo --version, rustc --version, go version, java --version, javac --version, ruby --version, docker --version

Docker (read-only): docker ps, docker images, docker logs

Data processing: jq, yq

Misc: man, help, type, stat, md5sum, sha256sum, shasum

Always Blocked Commands

These are blocked regardless of permission mode:

Configuration

Config file: ~/.config/host-terminal-mcp/config.yaml

Add custom allowed commands

Other options

HTTP Transport

For external services (e.g. a chatbot in Docker) that need to call your machine over the network:

Endpoints

Example

Architecture

Tools exposed to the AI:

Development

From source with Claude Desktop

Disclaimer

This software executes shell commands on your computer as directed by an AI model. AI models can behave unpredictably. Although permission controls (allowlist, blocklist, human-in-the-loop approval) are provided, they are offered on a best-effort basis and cannot guarantee safety. In particular, AI models may attempt to bypass permission controls — for example, by calling tool APIs to self-approve commands or by crafting inputs that circumvent the allowlist. The ask mode depends on the MCP client correctly presenting approval prompts to a human; not all clients do so, and this project has no control over client behavior. By installing or using this software you acknowledge that: (1) you are solely responsible for every command that runs on your system, (2) the authors and contributors disclaim all liability for any damage, data loss, security breach, or other harm arising from its use, (3) permission controls are a best-effort safeguard, not a security boundary, and (4) this software is provided "AS IS" without warranties of any kind, as stated in the Apache 2.0 License. Do not run this tool on production systems or systems containing sensitive data without understanding the risks.

License

Apache-2.0 — see LICENSE for the full text, including the warranty disclaimer and limitation of liability.