Host Terminal MCP

主机终端MCP

 

一 主控程序 该服务器允许AI助手在您的机器上运行终端命令，并具有权限控制。专为 克劳德桌面/合作 以及任何MCP兼容客户端。

运作原理

You (in Co-work)                      Your Mac
─────────────────                     ─────────
"run git status"
      │
      ▼
Claude (cloud)
      │  MCP tool call:
      │  execute_command("git status")
      ▼
Claude Desktop (local)
      │  forwards via stdio pipe
      ▼
host-terminal-mcp                     ◄── this project
      │  1. permission check ✅
      │  2. /bin/bash -c "git status"
      ▼
Terminal output flows back up the chain

克劳德桌面生成 host-terminal-mcp 作为子进程，使用MCP协议通过stdin/stdout进行通信。不涉及网络服务器，它是一个本地管道。

协同工作设置

1.安装

uv tool install host-terminal-mcp

或者使用pip：

pip install host-terminal-mcp

2.配置克劳德桌面

将MCP服务器添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

重要提示： Claude Desktop以最小的PATH运行(/usr/local/bin, /usr/bin, /bin, /usr/sbin, /sbin, /opt/homebrew/bin).如果您安装了 uv tool install 或 pip install --user，二进制文件可能在 ~/.local/bin/ 即 不 在Claude Desktop的PATH中。使用 完全绝对路径 以避免“没有这样的文件或目录”错误。

找到您的二进制路径：

which host-terminal-mcp
# Example output: /Users/you/.local/bin/host-terminal-mcp

然后在配置中使用该路径：

{
  "mcpServers": {
    "host-terminal": {
      "command": "/Users/you/.local/bin/host-terminal-mcp"
    }
  }
}

开始于 ask 模式（推荐--在运行未列出的命令之前提示您）：

{
  "mcpServers": {
    "host-terminal": {
      "command": "/Users/you/.local/bin/host-terminal-mcp",
      "args": ["--mode", "ask"]
    }
  }
}

提示： 如果全局安装到系统路径（例如。 /usr/local/bin/host-terminal-mcp)，你可以使用 "command": "host-terminal-mcp" 没有完整的路径。

3.重新启动克劳德桌面

退出并重新打开Claude Desktop。它将自动生成 host-terminal-mcp 过程。您可以验证它是否正在运行：

ps aux | grep host-terminal-mcp

4.使用它

在Claude.ai中打开一个联合工作会话（或直接使用Claude Desktop），然后问：

• “列出主目录中的文件”
• “在~/projects/myapp中显示git状态”
• “3000端口上运行的是什么？”
• “运行此项目的测试”

为什么这个工具

带护栏的码头通道。 三种权限模式允许您选择正确的访问级别——只读命令的锁定分配列表、 ask 提示您使用实时审批的模式 MCP激发，或沙盒环境的无限制模式。

教人工智能如何使用终端的技能。 该插件随附 技能 --Claude在运行时阅读的结构化指南。A. 代码库浏览器 技能教授项目导航模式（目录结构、清单检测、依赖关系跟踪）。A. 终端工作流 该技能教授安全shell执行（命令链、错误处理、进程管理）。克劳德不仅获得了访问权限，还获得了专业知识。

权限模式

如何 ask 模式工作

当Claude尝试运行不在允许列表中的命令时，服务器会使用 MCP激发 提示 你 （人类）直接在克劳德桌面UI中：

┌─────────────────────────────────────────────┐
│ The AI wants to run a command that is not   │
│ in the allow list:                          │
│                                             │
│   npm install                               │
│                                             │
│ Do you approve?                             │
│                                             │
│ [✓] Approve this command?                   │
│ [✓] Add to allowed list permanently?        │
│                                             │
│         [ Cancel ]  [ Submit ]              │
└─────────────────────────────────────────────┘

• 批准 --运行此会话的命令
• 永久添加到允许列表 --将命令保存到配置文件中，这样就不会再被询问
• 取消/拒绝 --命令被阻止

这是一个真正的人在循环中：克劳德不能自己批准命令。

注： 激发需要MCP客户端支持。如果您的客户端不支持它，未列出的命令将被拒绝，并显示一条消息，告诉您将它们添加到配置文件中。

权限检查顺序： 阻塞 （总是赢）> 允许 > 会议已批准 > 模式选择

默认允许的命令

这些命令（及其参数）是开箱即用的：

文件列表和导航： ls, ll, la, pwd, tree, find, locate, which, whereis, file

文件查看： cat, head, tail, less, more, bat, wc

搜索： grep, rg, ag, ack, fzf

Git（只读）： git status, git log, git diff, git show, git branch, git remote, git tag, git stash list, git rev-parse, git config --get, git config --list, git blame, git shortlog, git describe

系统信息： uname, hostname, whoami, id, date, uptime, df, du, free, top -l 1, ps

网络（只读）： ping -c, curl -I, curl --head, dig, nslookup, host, ifconfig, ip addr, netstat, ss

包管理器（仅供参考）： npm list, npm ls, npm view, npm show, npm outdated, pip list, pip show, pip freeze, brew list, brew info, apt list, dpkg -l

开发工具版本： python --version, python3 --version, node --version, npm --version, cargo --version, rustc --version, go version, java --version, javac --version, ruby --version, docker --version

Docker（只读）： docker ps, docker images, docker logs

数据处理： jq, yq

其他： man, help, type, stat, md5sum, sha256sum, shasum

始终被阻止的命令

无论权限模式如何，这些都会被阻止：

配置

配置文件： ~/.config/host-terminal-mcp/config.yaml

# Generate a default config file
host-terminal-mcp --init-config

添加自定义允许的命令

allowed_commands:
  - pattern: "docker compose logs"
    description: "Docker Compose service logs"
  - pattern: "docker compose ps"
    description: "Docker Compose service status"
  - pattern: "npm install"
    description: "Install npm packages"

  # Use regex for flexible matching
  - pattern: "^kubectl get "
    description: "Kubernetes get resources"
    is_regex: true

其他选项

permission_mode: allowlist          # allowlist | ask | allow_all
timeout_seconds: 300                # Max command execution time
max_output_size: 100000             # Max output chars (truncated beyond this)
shell: /bin/bash                    # Shell to use
allowed_directories:                # Commands restricted to these dirs
  - /Users/me
environment_passthrough:            # Env vars passed to commands
  - PATH
  - HOME
  - USER
  - LANG
  - LC_ALL

HTTP传输

对于需要通过网络调用您的机器的外部服务（例如Docker中的聊天机器人）：

# Install with HTTP extras
uv tool install 'host-terminal-mcp[http]'

# Start
host-terminal-mcp --http --port 8099

# Or in background
nohup host-terminal-mcp --http --port 8099 --mode ask > /tmp/host-terminal-mcp.log 2>&1 &

端点

示例

curl -X POST http://localhost:8099/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "docker compose ps", "working_directory": "/path/to/project"}'

建筑

src/host_terminal_mcp/
├── server.py        ← MCP stdio server, tool handlers, elicitation
├── http_server.py   ← Alternative HTTP/REST transport (FastAPI)
├── config.py        ← Permission rules, allowlist/blocklist, YAML config
└── executor.py      ← Runs commands via asyncio subprocess

暴露于AI的工具：

发展

git clone https://github.com/ankitaa186/host-terminal-mcp.git
cd host-terminal-mcp
make install        # Install all deps (venv auto-created)
make test           # Run tests
make lint           # Run linters
make format         # Format code
make run            # Run stdio server (foreground)
make run MODE=ask   # Run in ask mode
make inspect        # Test with MCP Inspector
make help           # Show all targets

来源：Claude Desktop

{
  "mcpServers": {
    "host-terminal": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/host-terminal-mcp", "host-terminal-mcp"]
    }
  }
}

免责声明

该软件根据AI模型的指示在您的计算机上执行shell命令。AI模型的行为可能不可预测。虽然提供了权限控制（允许列表、阻止列表、人在环审批），但它们是在尽最大努力的基础上提供的 不能保证安全特别是，人工智能模型可能会试图绕过权限控制，例如，通过调用工具API来自我批准命令，或者通过制作绕过允许列表的输入。这 ask 模式取决于MCP客户端正确地向人类呈现批准提示；并非所有客户都这样做，而且这个项目无法控制客户的行为。安装或使用此软件即表示您承认： (1) 您对系统上运行的每个命令负全部责任， (2) 作者和贡献者对因使用而产生的任何损害、数据丢失、安全漏洞或其他损害不承担任何责任， (3) 权限控制是一种尽力保护措施，而不是安全边界，以及 (4) 本软件按“原样”提供，不提供任何形式的保证，如 Apache 2.0许可证在不了解风险的情况下，不要在生产系统或包含敏感数据的系统上运行此工具。

许可证

Apache-2.0--参见 许可证 全文，包括保修免责声明和责任限制。