host-terminal

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

You (in Co-work)                      Your Mac
─────────────────                     ─────────
"run git status"
      │
      ▼
Claude (cloud)
      │  MCP tool call:
      │  execute_command("git status")
      ▼
Claude Desktop (local)
      │  forwards via stdio pipe
      ▼
host-terminal-mcp                     ◄── this project
      │  1. permission check ✅
      │  2. /bin/bash -c "git status"
      ▼
Terminal output flows back up the chain

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

uv tool install host-terminal-mcp

Or with pip:

pip install host-terminal-mcp

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:

which host-terminal-mcp
# Example output: /Users/you/.local/bin/host-terminal-mcp

Then use that path in the config:

{
  "mcpServers": {
    "host-terminal": {
      "command": "/Users/you/.local/bin/host-terminal-mcp"
    }
  }
}

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

{
  "mcpServers": {
    "host-terminal": {
      "command": "/Users/you/.local/bin/host-terminal-mcp",
      "args": ["--mode", "ask"]
    }
  }
}

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:

ps aux | grep host-terminal-mcp

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

Mode	Behavior	Safety
allowlist (default)	Only pre-approved read-only commands run	Safest
ask	Prompts you for approval on unlisted commands	Recommended for power users
allow_all	Everything runs except blocked commands	Dangerous

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: