LukeLamb/claude-terminal-mcp

A Claude Desktop extension that gives Claude terminal, filesystem, and background-job access on your local Linux machine.
Addresses a gap on Linux Claude Desktop where claude_desktop_config.json-style MCP servers aren't loaded (that mechanism is macOS/Windows only); on Linux, the only way to add tools is via installable extensions.
---
⚠️ Security — read this first
**Installing this extension grants Claude unrestricted shell access on your user account.** Anything your user can do from a terminal, Claude can do through this tool: read any file your user can read, modify anything they can modify, install software, open network connections, etc.
Treat installing this the same way you'd treat giving someone an SSH session to your machine. Don't install it on machines with sensitive data you wouldn't want Claude to see or on shared systems.
There is a minimal built-in safety denylist that refuses a handful of obviously-destructive one-liners (rm -rf /, rm -rf ~, fork bombs, dd/mkfs on raw disk devices, shutdown/reboot). **This is a last-resort safety net, not a sandbox.** A determined command can trivially bypass it. It exists so that a moment's inattention doesn't wipe your home directory.
To tighten the rails, edit the DENYLIST array at the top of server.js and rebuild. To remove them entirely, set DENYLIST = [] and rebuild.
---
What it does
Exposes 8 tools to Claude:
| Tool | Purpose |
|---|---|
| run_command(command, cwd?, timeout?, env?) | Run a shell command via bash -lc. Pipes, redirects, source venv/bin/activate && … all work. Returns stdout/stderr/exit_code. Output is capped at 100KB per stream; full transcript is always saved to a file and the path returned as log_path. |
| read_file(path, offset?, limit?) | Read a text file with optional line-range slicing. |
| list_directory(path) | Entries with type (file/dir), size, and mtime. |
| write_file(path, content, overwrite?) | Create or overwrite a text file. Parent directories are created. |
| run_background(command, cwd?) | Spawn a detached subprocess; returns a job_id. Use for long-running work you don't want to block the chat on (builds, training runs, servers). |
| read_background(job_id, tail?) | Status and last N lines of stdout/stderr for a background job. |
| list_background() | All jobs (running, exited, killed). |
| kill_background(job_id) | SIGTERM the job; SIGKILL after 5 seconds if it's still alive. |
Run state (transcripts, job scratch files) lives under /tmp/claude-term-mcp/ and is wiped at reboot.
---
Install
1. Download the latest Terminal.mcpb from the Releases page.
2. Open Claude Desktop → **Settings** → **Extensions**.
3. Scroll to the **Extension Developer** section at the bottom. Click **Install Extension** and pick the Terminal.mcpb file you downloaded.
4. Claude Desktop shows the extension details with a red "developer info not verified by Anthropic" warning. Verify you trust the source, then click **Install**.
5. At install time Claude Desktop will ask for a **Default working directory** — this is where shell commands run when Claude doesn't specify one. Pick your main projects folder, or leave empty to default to your home directory.