Claude Terminal MCP

What LukeLamb/claude-terminal-mcp does

LukeLamb/claude-terminal-mcp MCP server exposes eight local tools to Claude Desktop. The command tool runs shell input through bash -lc, so common shell features such as pipes, redirects, and environment activation commands are available. Results include standard output, standard error, and the process exit code. Each stream is capped at 100 KB in the immediate response, while the complete transcript is saved locally and returned through a log path.

Filesystem access covers reading text files with optional line offsets and limits, listing directory entries with type, size, and modification time, and creating or overwriting text files. Parent directories are created automatically when writing a file. These operations use the permissions of the local user running Claude Desktop.

Four additional tools manage detached processes. Claude can start a background command, inspect its status and recent output, list known jobs, or terminate a job. Termination sends SIGTERM first and follows with SIGKILL after five seconds if the process remains alive.

How it works

The extension runs locally rather than calling a hosted service. Its run transcripts and background-job data are kept under /tmp/claude-term-mcp/, which is cleared when the machine reboots. The extension itself does not collect data, send telemetry, or make network requests. Commands launched through it can still make network connections when the command requests them, such as with curl, wget, or git push.

A small built-in denylist blocks several clearly destructive command patterns, including recursive removal of root or the home directory, fork bombs, raw-device dd or mkfs operations, and shutdown or reboot commands. This is only a last-resort check and is not a sandbox; commands otherwise retain broad access available to the user account.

Setup and configuration

Install the latest Terminal.mcpb release from the repository's Releases page. In Claude Desktop, open Settings, choose Extensions, use Install Extension in the Extension Developer section, and select the bundle. Confirm the developer warning, choose a default working directory, enable the Terminal extension, and activate its tools from the connector or tools picker in a conversation.

The default working directory determines where commands run when no working directory is supplied. Leaving it blank uses the user's home directory. It can be changed later under Settings, Extensions, and Terminal. No npm install step is required because the extension is pure Node with no npm dependencies. Requirements are Claude Desktop 0.10.0 or newer, Node.js 16 or newer as a stated runtime requirement, and bash on the PATH; Claude Desktop bundles a recent Node runtime for the extension.

For source builds, LukeLamb/claude-terminal-mcp MCP server can be bundled by placing manifest.json, package.json, and server.js into Terminal.mcpb with the documented zip command, then importing that bundle through the same Extensions interface. Changes to the tool surface require matching updates to the manifest, and the version should be increased for Claude Desktop to recognize an update.

Tools and capabilities

• Run shell commands with optional working directory, timeout, and environment values.
• Read text files with optional line-range slicing.
• List directory contents and metadata.
• Write or overwrite text files and create missing parent directories.
• Start detached background jobs and retrieve their identifiers.
• Inspect, enumerate, and terminate background jobs.
• Retrieve full command transcripts from returned log paths.

Limitations and notes

Installing LukeLamb/claude-terminal-mcp MCP server grants Claude unrestricted shell access within the user's account. It can read and modify accessible files, install software, and open network connections, so it should not be treated as suitable for shared or sensitive machines without further controls. The denylist can be edited in server.js and removed or expanded before rebuilding, but changing it does not create isolation.

The README reports a known yellow banner saying that a tool result could not be submitted when Claude Desktop performs dynamic tool loading. According to the project documentation, the tool call still runs and returns; the banner is attributed to a client-backend protocol issue. The extension is documented for Linux and tested on macOS, while its installation flow is specifically based on Claude Desktop Extensions rather than the usual macOS/Windows configuration file mechanism.

Getting started with this LukeLamb/claude-terminal-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.