Borealis MCP

北欧MCP

用于AI代理与ALCF超级计算机（Aurora、Polaris、Sunspot）交互的MCP（模型上下文协议）服务器。

Borealis使Claude等AI代理能够提交和管理PBS作业，查询系统状态，并为ALCF系统生成优化的提交脚本。

特性

• PBS作业管理：提交、监视、保留、释放和删除作业
• 系统感知：自动检测并适应极光、北极星或太阳黑子
• 应用程序插件：针对特定领域工具的可扩展架构
• 模拟模式：在没有PBS访问的情况下进行本地开发和测试
• 远程访问：外部用户的SSH隧道支持

快速开始

安装

# Clone the repository with submodules
git clone --recursive https://github.com/argonne-lcf/borealis-mcp.git
cd borealis-mcp

# If you already cloned without --recursive, initialize submodules:
git submodule update --init --recursive

# Create virtual environment (Python 3.10+)
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

本地运行（模拟模式）

对于没有PBS访问权限的开发：

# Enable mock mode and run
BOREALIS_MOCK_PBS=1 python -m borealis_mcp.server

或者使用 --mock 标志：

python -m borealis_mcp.server --mock

在ALCF系统上运行

在Aurora、Polaris或Sunspot登录节点上，使用提供的启动脚本：

# Run on Aurora (default)
source start_borealis.sh

# Or specify the system explicitly
source start_borealis.sh aurora
source start_borealis.sh polaris
source start_borealis.sh sunspot

# Override the default account if needed
PBS_ACCOUNT=my_project source start_borealis.sh aurora

这 start_borealis.sh 脚本自动执行：

• 激活虚拟环境
• 集合 PBS_SERVER 对于目标系统
• 添加捆绑 pbs-python-api 到 PYTHONPATH
• 启动MCP服务器

Claude代码集成

地方发展（模拟模式）

添加到您的Claude Code MCP设置中(~/.claude/claude_desktop_config.json 在Mac上）：

{
  "mcpServers": {
    "borealis": {
      "command": "/path/to/borealis-mcp/venv/bin/python",
      "args": ["-m", "borealis_mcp.server", "--mock"],
      "cwd": "/path/to/borealis-mcp"
    }
  }
}

在ALCF登录节点上（直接SSH启动）

Claude Code可以直接通过SSH启动MCP服务器。因为Claude Code无法响应交互式提示，SSH必须在不需要密码或MFA挑战的情况下连接。建议的方法是 SSH控制主机，其在已经认证的会话上复用后续连接。

步骤1：配置SSH ControlMaster

将以下内容添加到您的本地 ~/.ssh/config:

Host aurora.alcf.anl.gov
    ControlMaster auto
    ControlPath ~/.ssh/control-%h-%p-%r
    ControlPersist 8h

ControlPersist 8h 在您关闭主连接后，它将保持8小时的活动状态，因此Claude Code可以在没有提示的情况下重新连接。

步骤2：打开主连接

在启动Claude Code之前，手动打开一个SSH会话（这是您完成MFA的地方）：

ssh aurora.alcf.anl.gov

让这个终端打开，或者让 ControlPersist 退出后把它放在后台。

步骤3：配置Claude代码

后续的SSH连接将重用经过身份验证的主机。添加到您的Claude Code MCP设置中(~/.claude/settings.json):

{
  "mcpServers": {
    "borealis": {
      "command": "ssh",
      "args": [
        "aurora.alcf.anl.gov",
        "cd /path/to/borealis-mcp && ./start_borealis.sh aurora"
      ]
    }
  }
}

对于Polaris或Sunspot，请相应地替换主机和系统名称：

{
  "mcpServers": {
    "borealis": {
      "command": "ssh",
      "args": [
        "polaris.alcf.anl.gov",
        "cd /path/to/borealis-mcp && ./start_borealis.sh polaris"
      ]
    }
  }
}

备注: start_borealis.sh 必须 *执行* （未来源），以便它设置PBS环境变量，然后启动服务器。Claude Code通过stdio与它通信。

通过SSH隧道进行远程访问

这是在从本地机器连接到ALCF系统时，使用北欧化工与克劳德代码的推荐工作流程。

安全说明：HTTP传输没有身份验证。它绑定到 localhost 只有，但同一登录节点上的其他用户可能会访问您的服务器。在受信任的网络上使用。基于令牌的身份验证计划在未来发布。

步骤1:在Aurora上进行一次性设置

登录并克隆存储库：

ssh username@aurora.alcf.anl.gov

git clone --recursive https://github.com/argonne-lcf/borealis-mcp.git
cd borealis-mcp

# If you already cloned without --recursive:
git submodule update --init --recursive

python3 -m venv venv
source venv/bin/activate
pip install -e .

步骤2：在Aurora上设置您的PBS帐户

将您的项目分配添加到 ~/.bashrc （或 ~/.bash_profile)因此，服务器可以使用：

echo 'export PBS_ACCOUNT=your_project_allocation' >> ~/.bashrc
source ~/.bashrc

步骤3：启动服务器和隧道

选项A--单个命令（推荐）。 从你的 本地机器，运行辅助脚本。它建立SSH隧道，并通过一个MFA提示符在单个连接上启动MCP服务器：

./tools/start_borealis_tunnel.sh your_aurora_username
# Optional second argument overrides the remote repo path (default: ~/borealis-mcp)
./tools/start_borealis_tunnel.sh your_aurora_username ~/path/to/borealis-mcp

保持这个终端打开。按 Ctrl+C 停止服务器并关闭隧道。

选项B——两个终端。 如果您想单独管理服务器和隧道（需要两次MFA），请使用此选项。

*端子1* --登录Aurora并启动服务器：

ssh username@aurora.alcf.anl.gov
cd ~/borealis-mcp
source start_borealis.sh aurora          # sets PBS_SERVER, PBS_ACCOUNT, PYTHONPATH
python -m borealis_mcp.server --transport http --port 9000

*2号航站楼* --从本地计算机打开端口转发隧道：

ssh -N -L 9000:localhost:9000 username@aurora.alcf.anl.gov

步骤4：配置Claude代码

Claude Code无法使用直接连接到服务器 type: "http" 或 type: "sse" 因为它尝试了FastMCP没有实现的OAuth元数据发现。建议的解决方法是 mcp-remote，由MCP团队维护的stdio包装器，用于正确处理HTTP连接。

附属国： Node.js 18或更高版本（适用于 npx).证实 node --version。从安装 如果需要的话。

将以下内容添加到本地计算机上的Claude Code MCP设置中。设置文件为 ~/.claude/settings.json （用户范围）或 .claude/settings.json 在特定项目中：

{
  "mcpServers": {
    "borealis": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9000/mcp"]
    }
  }
}

npx -y 下载并运行 mcp-remote 首次使用时自动；不需要单独的安装步骤。

步骤5：启动Claude代码

隧道打开，服务器运行，正常启动Claude Code。这 borealis MCP服务器将可用，Claude可以代表您在Aurora上提交和管理PBS作业。

可用工具

核心PBS工具

• submit_pbs_job -从脚本文件提交作业
• get_job_status -获取特定作业的状态
• list_jobs -列出具有可选状态/队列筛选器的作业
• delete_job -删除作业
• hold_job / release_job -保留或释放工作
• get_queue_info -获取队列信息
• get_system_info -获取当前系统配置

应用软件工具

• build_hello_world_submit_script -生成MPI hello world脚本
• get_hello_world_info -获取hello world配置
• build_generic_submit_script -为任何可执行文件生成脚本
• get_generic_info -获取通用作业配置

可用资源

• pbs://system/current -当前系统配置
• pbs://systems/all -所有可用系统
• pbs://queues -队列信息
• pbs://jobs/summary -按州分列的工作摘要
• pbs://filesystems -文件系统信息

配置

环境变量

系统配置

系统配置在 config/systems/。参见 config/systems/README.md 用于添加新系统。

发展

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (automatically uses mock mode)
pytest

添加新应用程序

1. 在下创建新目录 src/borealis_mcp/applications/
2. 实施 Application 类继承自 ApplicationBase
3. 服务器启动时自动发现应用程序

看 applications/hello_world/ 举个例子。

许可证

麻省理工学院