MCP Compute Scout

MCP计算侦察员

MCP（模型上下文协议）服务器，用于检查SSH可访问服务器上的计算和GPU可用性。非常适合拥有多台计算服务器的研究小组和组织。

特性

• 服务器发现：检查所有服务器的CPU、内存和GPU使用情况
• GPU监控：跟踪GPU利用率、内存和正在运行的进程
• 智能选择：根据您的要求找到最佳可用服务器
• Slash命令：使用直观 /scout_* Claude Desktop中的命令
• 快速并行：使用缓存同时检查多个服务器
• 灵活配置：基于YAML的配置，支持模式

安装

使用pipx（推荐）

pipx 是推荐的安装方法，因为它创建了一个隔离的环境，并使命令全局可用：

# Install pipx if you haven't already
brew install pipx  # macOS with Homebrew
# or
python -m pip install --user pipx

# Clone and install
git clone https://github.com/matsengrp/mcp-compute-scout.git
cd mcp-compute-scout
pipx install -e .

替代方案：使用pip

如果您更喜欢管理自己的虚拟环境：

git clone https://github.com/matsengrp/mcp-compute-scout.git
cd mcp-compute-scout
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

配置

1. 复制并自定义配置文件：

mkdir -p ~/.config/mcp-compute-scout
cp config/servers.yml ~/.config/mcp-compute-scout/

1. 编辑 ~/.config/mcp-compute-scout/servers.yml 要添加服务器，请执行以下操作：

servers:
  - name: myserver1
    host: myserver1.example.com
    has_gpu: true
    
  # Use patterns for server groups
  - pattern: "node{01..10}"
    has_gpu: true

ssh:
  username: "${USER}"  # Uses environment variable
  timeout: 10

Claude桌面集成

添加到您的 claude_desktop_config.json:

如果与pipx一起安装（推荐）：

{
  "mcpServers": {
    "compute-scout": {
      "command": "mcp-compute-scout",
      "env": {
        "SSH_USER": "your-username"  // Optional, defaults to current user
      }
    }
  }
}

如果在虚拟环境中与pip一起安装：

{
  "mcpServers": {
    "compute-scout": {
      "command": "/path/to/mcp-compute-scout/.venv/bin/python",
      "args": ["-m", "mcp_compute_scout"],
      "env": {
        "SSH_USER": "your-username"  // Optional, defaults to current user
      }
    }
  }
}

快速入门（克劳德代码）

已经在工作了？跳到步骤3！

1. 安装：

pipx install git+https://github.com/matsengrp/mcp-compute-scout.git

1. 完全重新启动Claude代码：

- 关闭所有Claude Code会话（不仅仅是Ctrl+D） - 重新打开克劳德代码 - *重要提示：MCP服务器需要完全重新启动才能正确连接*

1. 在中配置服务器 ~/.config/mcp-compute-scout/servers.yml:

servers:
  - name: myserver
    host: myserver.example.com
    has_gpu: true

1. 测试其工作原理：

问问克劳德： *“myserver上有哪些GPU？”*

就是这样！ 如果你收到服务器信息，你就可以开始了。无需验证配置或运行复杂的测试。

常见查询

• “\[服务器\]上有哪些GPU？”
• “显示所有服务器状态”
• “查找CPU使用率低的GPU服务器”
• “有免费的服务器吗？”

Claude代码集成（高级）

MCP配置

全局配置（推荐）： 添加到 顶层 你的 ~/.claude.json:

{
  "mcpServers": {
    "compute-scout": {
      "command": "mcp-compute-scout",
      "env": {
        "SSH_USER": "your-username"
      }
    }
  },
  "numStartups": 118,
  ...
}

项目配置： 或添加到项目的 .claude.json:

{
  "mcpServers": {
    "compute-scout": {
      "command": "mcp-compute-scout"
    }
  }
}

重要提示： 全局配置使工具在任何地方都可用。项目配置仅在该特定目录中有效。

开发安装

git clone https://github.com/matsengrp/mcp-compute-scout.git
cd mcp-compute-scout
pipx install -e .  # Changes auto-update

自然语言使用示例

与其记住复杂的斜线命令，不如自然地问：

You: "What's the status of ermine?"
Claude: [Shows server details with CPU, memory, GPU usage]

You: "Are there any free GPU servers?"
Claude: [Lists servers with available GPUs]

You: "Find me a server with at least 32GB free memory"
Claude: [Shows best matching servers]

团队项目设置

添加到您的项目 CLAUDE.md:

## Compute Scout Integration

This project uses MCP Compute Scout for checking server resources.

**Available Commands:**
- Ask about server status: "What's the status of [server]?"
- Find resources: "Find a server with [requirements]"
- Check GPU availability: "Are there free GPUs?"
- View all servers: "Show me all server statuses"

**Setup:** MCP Compute Scout installed globally with pipx. 
MCP server configured in ~/.claude.json.

**Documentation:** https://github.com/matsengrp/mcp-compute-scout

用法

克劳德桌面Slash命令

配置后，以下斜线命令在Claude Desktop中可用：

/scout_all

显示所有服务器及其当前资源使用情况：

Server    Status   CPU      Memory   Load Avg        GPU Usage   GPU Memory
--------  -------  -------  -------  --------------  ----------  ------------
ermine    online   15.2%    45.3%    0.52, 0.48, 0.41  25%        30% (3072/10240 MB)
quokka    online   5.1%     22.1%    0.15, 0.20, 0.18  No GPU     No GPU

/scout_gpu

仅显示具有详细GPU信息的启用GPU的服务器：

Server    Status   CPU     Memory   GPU Usage       GPU Memory
--------  -------  ------  -------  -------------   ----------------
ermine    online   15.2%   45.3%    25%             30% (3072/10240 MB)
orca01    online   89.5%   78.2%    95% (avg of 4)  85% (34816/40960 MB)

/scout_server ermine

获取特定服务器的详细信息：

Server: ermine
Status: online
CPU Usage: 15.2%
Memory Usage: 45.3%
Load Avg: 0.52, 0.48, 0.41
GPU Usage: 25%
GPU Memory: 30% (3072/10240 MB)

GPU Processes:
  - python (PID: 12345, Memory: 2048 MB)
  - jupyter (PID: 23456, Memory: 1024 MB)

/scout_find need_gpu=true max_cpu=50

找到符合您条件的最佳服务器：

Best available server: orca03

Status: online
CPU Usage: 12.5%
Memory Usage: 35.2%
Load Avg: 0.25, 0.30, 0.28
GPU Usage: 10%
GPU Memory: 5% (512/10240 MB)

/scout_free

快速查看低负载服务器（CPU\<20%，内存\<50%）：

Server    Status   CPU     Memory   Load Avg         GPU Usage
--------  -------  ------  -------  --------------   ----------
quokka    online   5.1%    22.1%    0.15, 0.20, 0.18  No GPU
orca03    online   12.5%   35.2%    0.25, 0.30, 0.28  10%

高级用法

JSON输出

所有命令都支持JSON输出以供编程使用：

/scout_all format=json
/scout_find need_gpu=true format=json

以编程方式查找服务器

这 /scout_find 命令支持多个筛选器：

• need_gpu：要求GPU可用性（真/假）
• max_cpu：最大CPU使用率百分比（0-100）
• min_memory_gb：最小可用内存（GB）

示例：查找CPU使用率低于30%的GPU服务器：

/scout_find need_gpu=true max_cpu=30

SSH配置

该工具使用您系统的SSH配置。确保：

1. SSH密钥设置为无密码访问
2. 服务器可以通过SSH访问
3. 您的SSH配置(~/.ssh/config)具有适当的设置

SSH配置条目示例：

Host orca*
    User myusername
    IdentityFile ~/.ssh/id_rsa
    StrictHostKeyChecking no

自定义命令

您可以在中自定义用于检查系统资源的命令 servers.yml:

commands:
  cpu_usage: |
    # Your custom CPU check command
    top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1
  
  gpu_usage: |
    # Your custom GPU check command
    nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader,nounits

故障排除

“未知主机”错误

• 验证服务器主机名是否正确
• 检查你的SSH配置 /etc/hosts

“权限被拒绝”错误

• 确保已设置SSH密钥身份验证
• 检查配置中的用户名

GPU信息未显示

• 验证 nvidia-smi 已安装在服务器上
• 检查一下 has_gpu: true 为GPU服务器设置

反应缓慢

• 在配置中调整SSH超时
• 检查网络连接
• 缓存TTL可以调整（默认值：30秒）

贡献

欢迎投稿！请随时提交问题和拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件