一个 Claude Desktop 扩展，为您的本地 Linux 机器上的 Claude 提供终端、文件系统和后台作业访问权限。
解决了 Linux 版 Claude Desktop 上无法加载 claude_desktop_config.json 风格 MCP 服务器的问题（该机制仅适用于 macOS/Windows）；在 Linux 上，添加工具的唯一方法是通过可安装的扩展。
安装此扩展即授予 Claude 对您用户帐户的无限制 shell 访问权限。 您的用户在终端中能做的任何事情，Claude 都可以通过此工具完成：读取您的用户可以读取的任何文件、修改他们可以修改的任何内容、安装软件、打开网络连接等。
安装此扩展时，请将其视为授予某人访问您机器的 SSH 会话。请勿在包含您不希望 Claude 查看的敏感数据的机器或共享系统上安装它。
内置了一个最小的安全拒绝列表，拒绝了一些明显的破坏性单行命令（rm -rf /、rm -rf ~、fork 炸弹、原始磁盘设备上的 dd/mkfs、shutdown/reboot）。这是一个最后的安全网，而不是沙箱。 坚定的命令可以轻易绕过它。它的存在是为了防止因一时疏忽而清空您的主目录。
要加强限制，请编辑 server.js 顶部的 DENYLIST 数组并重新构建。要完全移除它们，请设置 DENYLIST = [] 并重新构建。
Related MCP server: claude-linux-mcp
向 Claude 公开 8 个工具：
工具 | 用途 |
| 通过 |
| 读取带有可选行范围切片的文本文件。 |
| 列出条目，包含类型（文件/目录）、大小和修改时间。 |
| 创建或覆盖文本文件。会自动创建父目录。 |
| 生成一个分离的子进程；返回一个 |
| 后台作业的状态以及 stdout/stderr 的最后 N 行。 |
| 所有作业（运行中、已退出、已终止）。 |
| 向作业发送 SIGTERM；如果 5 秒后仍然存活，则发送 SIGKILL。 |
运行状态（记录、作业临时文件）位于 /tmp/claude-term-mcp/ 下，并在重启时清除。
从 Releases 页面 下载最新的 Terminal.mcpb。
打开 Claude Desktop → Settings → Extensions。
滚动到底部的 Extension Developer 部分。点击 Install Extension 并选择您下载的 Terminal.mcpb 文件。
Claude Desktop 会显示带有红色“开发者信息未经 Anthropic 验证”警告的扩展详情。确认您信任该来源，然后点击 Install。
安装时，Claude Desktop 会询问 Default working directory（默认工作目录）——这是 Claude 在未指定目录时运行 shell 命令的位置。选择您的主要项目文件夹，或留空以默认为您的主目录。
回到 All extensions，确保 Terminal 已开启。
在聊天中，打开连接器/工具选择器并为该对话启用 Terminal。
您可以稍后从 Settings → Extensions → Terminal 更改默认工作目录。
Linux 上的 Claude Desktop ≥ 0.10.0（也在 macOS 上测试过）
Node.js ≥ 16（Claude Desktop 捆绑了它用于运行扩展的最新 Node，因此不需要系统 Node）
PATH 中的 bash
无需 npm install 步骤 — 该扩展是零依赖的纯 Node 程序。
所有配置均通过 Claude Desktop 的 UI 在安装时或在 Settings → Extensions → Terminal 下完成。
字段 | 类型 | 用途 |
Default working directory | 目录 | Claude 未指定目录时 shell 命令运行的位置。留空则默认为 |
要自定义拒绝列表或其他行为，请编辑 server.js 并重新构建（见下文）。
黄色横幅：“Tool result could not be submitted. The request may have expired or the connection was interrupted.” 这会在触发 Claude 动态工具加载步骤的每一轮中出现。404 错误发生在向 Anthropic 后端提交工具搜索结果时，而不是 MCP 工具本身——您的工具调用在横幅出现后会立即正确运行并返回。这只是外观问题。同样的问题也出现在官方的文件系统扩展中。这很可能是客户端↔后端协议不匹配，将在未来的 Claude Desktop 版本中修复。
git clone https://github.com/LukeLamb/claude-terminal-mcp
cd claude-terminal-mcp
# Edit whatever you want in server.js / manifest.json.
# If you change the tool surface, update both places.
# Bump the version in manifest.json so Claude Desktop treats the install as an update.
# Build the bundle:
zip -j Terminal.mcpb manifest.json package.json server.js
# Then install Terminal.mcpb via Claude Desktop → Settings → Extensions → Install Extension.Settings → Extensions → All extensions → Terminal → Remove。
没有任何数据离开您的机器。 此扩展完全在本地运行：
数据收集： 无。该扩展不会向外拨号、发送遥测数据或进行任何自身的网络请求。您观察到的所有网络调用都是您要求 Claude 运行的（例如 curl、wget、git push）。
数据使用与存储： 命令记录（不包括 stdin，包括 stdout + stderr + 退出代码）被写入 /tmp/claude-term-mcp/runs/<timestamp>.log，以便 Claude 稍后可以在同一对话中引用它们。后台作业状态（命令、pid、stdout/stderr 日志文件、退出代码、状态）被写入 /tmp/claude-term-mcp/jobs/<job-id>/。
第三方共享： 无。此扩展不会向 Anthropic、扩展作者或任何第三方传输任何内容。（Claude Desktop 本身作为正常聊天流程的一部分，会单独将工具输入/输出发送给 Anthropic——这是您与 Anthropic 的关系，而非此扩展的关系。）
保留期限： /tmp/claude-term-mcp/ 在每次重启时都会被清除。要手动清除：rm -rf /tmp/claude-term-mcp。
权限范围： 命令以您自己的用户权限运行——与您在终端中输入它们的效果相同。
联系方式 / 问题： 在 https://github.com/LukeLamb/claude-terminal-mcp/issues 提交 issue。
MIT。自由使用，感谢署名，不提供任何担保。
Terminate a running background job (SIGTERM, then SIGKILL after 5s).
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, and the description adds specific behavioral details (SIGTERM then SIGKILL after 5s), which goes beyond the annotation. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core purpose and key details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema, destructiveHint annotation), the description covers the main behavior but lacks information on error handling, return values, or what happens if the job_id is invalid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (job_id) with no description (0% coverage), and the description does not elaborate on this parameter or its format. The description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('terminate') and the resource ('running background job'), and explicitly mentions the signal sequence (SIGTERM then SIGKILL after 5s). This distinguishes it from sibling tools like list_background and run_background.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for forceful termination but does not explicitly state when to use this tool versus alternatives, nor does it provide any exclusions or prerequisites. The context of sibling names provides some guidance, but it is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all background jobs (running, exited, killed).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description confirms this is a list operation. It adds behavioral context by specifying the job states included (running, exited, killed), which annotations do not cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with 8 words, front-loading the purpose. Every word adds value, and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description covers what the tool does and the states returned. However, it lacks details on the output structure (e.g., fields like job ID or status), which would help an agent interpret results without schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage. The description correctly omits parameter details as none exist. No additional parameter info is needed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all background jobs' with specific states (running, exited, killed). The verb 'List' and resource 'background jobs' are unambiguous, and the states differentiate it from siblings like kill_background or run_background.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an agent needs to view all background jobs, but it does not provide explicit guidance on when to use this tool versus alternatives like read_background for job details or kill_background for termination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List entries in a directory with type, size, and mtime.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds value by explicitly listing the fields returned (type, size, mtime), which is beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is clear and to the point, front-loading the purpose and output fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter and no output schema, the description covers the basics but lacks details about error handling, recursion, symlinks, or output structure. Given the low complexity, it is minimally viable but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'path' has no description in the schema (0% coverage), and the tool description does not clarify the expected format (absolute/relative), allowed values, or behavior for missing paths. The parameter name is self-explanatory, but the description should compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('list') and resource ('directory entries') and specifies the output fields (type, size, mtime), which distinguishes it from siblings like read_file that read file contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidelines on when to use vs alternatives. While the function is straightforward, the description does not mention when not to use or provide context about prerequisites (e.g., path must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read status and last N lines of stdout/stderr for a background job. tail=0 returns full logs.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| tail | No | Number of trailing lines to return. Default 100. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, indicating safety. Description adds detail about reading stdout/stderr and the tail=0 behavior for full logs, enhancing transparency without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. Front-loaded with verb and resource, efficiently conveying core functionality and a key parameter behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should clarify return format. It mentions 'status and last N lines' but lacks specifics on structure, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only tail has description). The description adds value for tail ('tail=0 returns full logs') but does not describe job_id beyond context of 'background job'. Partially compensates for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read status and last N lines of stdout/stderr for a background job', specifying the verb and resource. It distinguishes from sibling tools like kill_background (kill) and run_background (start).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for reading background job output but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives like read_file for non-job outputs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a text file with optional line-range slicing.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| offset | No | 0-indexed starting line. Default 0. | |
| limit | No | Max lines to return. Default 2000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, indicating non-destructive behavior. The description adds the line-range slicing behavior, which is not covered by annotations. However, it does not disclose other behavioral traits like encoding assumptions, file existence errors, or output format. With annotations covering safety, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, with no unnecessary verbiage. It is front-loaded with the core action and concisely adds scope. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the tool's simplicity, the description covers the input and basic behavior. However, it omits details like return format (list of strings?), error handling (e.g., file not found), or constraints (e.g., file must be UTF-8). It is minimally adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (offset and limit have descriptions, path does not). The description mentions 'line-range slicing', which reinforces offset and limit, but does not explicitly describe the path parameter beyond implying it refers to a text file. It adds some context but does not fully compensate for the missing schema description on path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Read a text file with optional line-range slicing' uses a specific verb (Read) and resource (text file), and adds the line-range slicing detail that distinguishes it from sibling tools like write_file or list_directory. It clearly communicates the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading text files, optionally with line-range slicing. However, it does not explicitly state when not to use this tool or mention alternatives (e.g., using run_command with cat). The context is clear but lacks exclusion guidance, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a long-running command in the background. Returns a job_id you can poll with read_background.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| cwd | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds 'long-running' context and return of job_id beyond annotations (destructiveHint, openWorldHint). Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but could benefit from structured listing of parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks mentions of kill_background for cancellation or list_background for querying. No output schema so return format (job_id type) is unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, description provides no additional meaning for 'command' or 'cwd' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Start', resource 'long-running command in the background', and output 'job_id' for polling. Distinguishes from siblings like read_background.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions polling via read_background, guiding usage. Could explicitly contrast with run_command for foreground tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a shell command via bash -lc on the user's machine. Returns stdout/stderr/exit_code. Default cwd is the user-configured default working directory (or $HOME if unset). Output capped at 100KB per stream; full transcript saved to log_path.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to run. Pipes, redirects, `source venv/bin/activate && …` all work. | |
| cwd | No | Working directory. Defaults to the user-configured default working directory (or the user's home directory if unset). | |
| timeout | No | Timeout in seconds. Default 120. | |
| env | No | Extra environment variables to set for this command. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds useful behavioral details beyond annotations: output capped at 100KB, full transcript saved to log_path, default cwd behavior, and use of bash -lc. Does not contradict destructiveHint or openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently convey purpose, execution method, defaults, and output limits. Front-loaded with key information, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core functionality, defaults, and output limits. Could mention blocking nature or security implications, but given no output schema and good annotations, it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100% coverage). Description adds minor value for 'command' parameter (notes pipes/redirects work) but otherwise repeats schema info. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs a shell command via bash -lc, returns stdout/stderr/exit_code. Distinguishes from sibling tools like list_directory or kill_background by focusing on command execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives like run_background or read_file. The description only states what it does, not when to prefer it over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or overwrite a text file. Parent directories are created.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| overwrite | No | Default true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true. The description adds that parent directories are created, providing useful behavioral context beyond the annotation. It does not mention file size limits or encoding, but for a simple write tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences with no unnecessary words. The key action and side effect (parent directory creation) are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core functionality but omits edge cases (e.g., behavior when overwrite is false and file exists). With no output schema, the side effects and return values are not disclosed. Overall minimal viable but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only overwrite has a description). The tool description does not elaborate on path or content parameters, failing to compensate for the low coverage. The description only implies content is text, no parameter-specific details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create or overwrite a text file' with a specific verb and resource. The additional detail about parent directories being created distinguishes it from siblings like read_file and run_command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as run_command or read_file. The description omits when not to use it or mention of trade-offs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0kill_backgroundlist_backgroundlist_directoryread_backgroundread_filerun_backgroundrun_commandwrite_fileScored across 8 tools
Each tool has a distinct purpose: run_command for synchronous commands, run_background for long-running, and separate tools for file operations and background job management. No overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., kill_background, list_directory, read_file), making the set predictable.
With 8 tools, the server covers essential terminal operations (command execution, file read/write, listing, background jobs) without excessive tool count.
Core operations are present, but missing file deletion, rename, and persistent directory change tools; however, these can be accomplished via run_command, so only minor gaps.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Shared memory and actions for Claude, Kiro, OpenAI, Cursor, and other MCP-compatible AI clients.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
