cowork-terminal-mcp

MCP server that gives Claude Cowork access to the host terminal.

What is this?

Claude Cowork runs inside a sandboxed Linux VM on your machine, so it cannot directly execute commands on the host. This MCP server runs on the host and exposes a single execute_command tool over stdio, bridging that gap.

(It also works with Claude Code CLI if you want the same host-terminal escape hatch there.)

Installation

This server runs on the host machine. Pick the instructions that match how you use Claude.

For Claude Cowork

Claude Cowork reads MCP servers from the Claude Desktop config and passes them through into its sandboxed VM. Edit (or create) Claude Desktop's config file:

• Windows (Microsoft Store install): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
• Windows (standard install): %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server:

{
  "mcpServers": {
    "cowork-terminal": {
      "command": "npx",
      "args": ["-y", "cowork-terminal-mcp"]
    }
  }
}

On Windows, wrap the command in cmd /c so npx resolves correctly:

{
  "mcpServers": {
    "cowork-terminal": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cowork-terminal-mcp"]
    }
  }
}

Restart Claude Desktop, then open a Cowork session — the execute_command tool will be available.

For Claude Code (CLI)

claude mcp add cowork-terminal -- npx -y cowork-terminal-mcp

On Windows (outside WSL):

claude mcp add cowork-terminal -- cmd /c npx -y cowork-terminal-mcp

Run directly

npx cowork-terminal-mcp

Install globally

npm install -g cowork-terminal-mcp
cowork-terminal-mcp

Requirements

• bash — commands always run in bash.
  • On Windows: Git for Windows must be installed. The server resolves the Git Bash binary by absolute path (searching Program Files\Git\bin, Program Files\Git\usr\bin, and the %LOCALAPPDATA%\Programs\Git variants) and never falls back to System32\bash.exe (which is the WSL launcher — WSL can't see Windows PATH or run .exe files). If Git Bash is not found, the server fails to start with a clear error.
  • On macOS/Linux: uses whatever bash is on PATH.

Available tools

| Tool | Description | |------|-------------| | execute_command | Run a bash command on the host terminal |

execute_command

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | command | string | (required) | The bash command to execute | | cwd | string | Home directory | Working directory (prefer this over cd <path> &&) | | timeout | number | 30000 | Timeout in milliseconds | | env | Record<string, string> | — | Additional environment variables |

Returns JSON with stdout, stderr, exitCode, and timedOut fields. Output is capped at 1MB per stream.

Multi-line content

Use a bash heredoc. The \n characters in the JSON command string are decoded to real newlines by the JSON parser before bash sees them — so heredocs work as expected:

{
  "command": "gh pr create --title \"My PR\" --body \"$(cat <<'EOF'\n## Summary\n\n- First item\n- Second item\nEOF\n)\"",
  "cwd": "/path/to/repo"
}

Do NOT embed \n inside double-quoted bash strings hoping the shell will interpret them — it won't. Use heredocs for any multi-line argument.

Security

This server intentionally provides unrestricted shell access to the host machine. It is designed for local use only, where you trust the client connecting to it.

• Run only on machines you trust
• Do not expose over a network
• The stdio transport ensures only a local process can connect
• Review commands before approving execution

Development

git clone https://github.com/marius-bughiu/cowork-terminal-mcp.git
cd cowork-terminal-mcp
npm install
npm run build
npm start

Use watch mode during development:

npm run dev

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT