Purpose
claude-terminal-mcp is an extension for Claude Desktop on the Linux platform that lets Claude access your local terminal, file system, and background tasks. It addresses a gap in Claude Desktop on Linux: the MCP server loading mechanism similar to claude_desktop_config.json only works on macOS/Windows, while on Linux the only way to add tools is to use installable extensions. The project is open source, MIT-licensed, and has zero dependencies.
Main capabilities
The extension exposes 8 tools to Claude, covering terminal command execution, file system operations, and background task management. Runtime state (command records, task temporary files) is stored in /tmp/claude-term-mcp/ and is cleared on every restart.
Installation and usage
- Download the latest Terminal.mcpb from the Releases page.
- Open Claude Desktop → Settings → Extensions.
- Scroll to the Extension Developer section at the bottom, click Install Extension, and select the downloaded Terminal.mcpb file.
- Claude Desktop will display the extension details with a red "developer info not verified by Anthropic" warning. After confirming you trust the source, click Install.
- During installation, you will be asked to set a Default working directory, which is where commands run when Claude does not specify a directory. You can choose your main project folder, or leave it blank to default to your home directory.
- Return to All extensions and make sure Terminal is enabled.
- Open the connector/tool selector in the conversation and enable Terminal for that conversation.
The default working directory can later be changed in Settings → Extensions → Terminal. All configuration is done through the Claude Desktop interface. To customize the deny list or other behavior, you need to edit server.js andRebuilt.
Use Cases and Limitations
Intended for users who want to give Claude Desktop local terminal and file access capabilities on Linux. Requires Claude Desktop ≥ 0.10.0 (Linux; macOS also tested), Node.js ≥ 16 (the Node bundled with Claude Desktop is sufficient to run this extension; no system Node is needed), and no npm install is required—the extension is pure Node with zero dependencies.
Security limitations require special attention: installing this extension grants Claude unrestricted shell access under your user account. Everything your user can do in a terminal, Claude can do through this tool: read any file you can read, modify anything you can modify, install software, establish network connections, and so on. Treat installing it like "giving someone an SSH session to your machine." Do not install it on a machine containing sensitive data you do not want Claude to see, and do not install it on a shared system.
There is only one minimal built-in safety denylist, which rejects a few obviously destructive one-liners (rm -rf /, rm -rf ~, fork bombs, dd/mkfs to bare disk devices, shutdown/reboot). This is only a last-resort safety net, not a sandbox; intentional commands can easily bypass it. Its purpose is to prevent a moment of carelessness from wiping your home directory. To tighten restrictions, edit the DENYLIST array at the top of server.js and rebuild; to remove it entirely, set DENYLIST = [] and rebuild.
Privacy Notes
No data leaves your machine; the extension runs entirely locally: it collects no data, sends nothing back, transmits no telemetry, and makes no network requests of its own; any network calls you observe are ones you asked Claude to run (such as curl, wget, git push). Command records (excluding stdin, including stdout + stderr + exit code) are written to /tmp/claude-term-mcp/runs/<timestamp>.log for Claude to reference later in the same conversation; background task status (command, pid, stdout/stderr log files, exit code, status) is written to /tmp/claude-term-mcp/jobs/<job-id>/.Nothing is transmitted to Anthropic, the extension author, or any third party (Claude Desktop itself sends tool input/output to Anthropic during the normal chat flow; that is a relationship between Anthropic and you, not something this extension does). /tmp/claude-term-mcp/ is cleared on every restart, and can also be cleared manually with rm -rf /tmp/claude-term-mcp. Commands run with your own user privileges, the same as if you typed them into a terminal.
Known Issues
The yellow banner "Tool result could not be submitted. The request may have expired or the connection was interrupted." appears every time a turn triggers Claude's dynamic tool loading step. This 404 occurs when submitting tool search results to the Anthropic backend, not with the MCP tool itself—after the banner appears, your tool call executes and returns correctly immediately. This is a display-layer issue that also affects the official Filesystem extension; it may be a protocol mismatch between the client and the backend and is expected to be fixed in a future Claude Desktop version.
License
MIT. Free to use, attribution welcome, no warranty. Issue reports can be submitted at https://github.com/LukeLamb/claude-terminal-mcp/issues .
