# matpool-mcp-server

**Repository Path**: btc8/matpool-mcp-server

## Basic Information

- **Project Name**: matpool-mcp-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: EPL-1.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MatPool MCP Server

[矩池云官网](https://matpool.com/) | [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)

通过 MCP 协议管理 MatPool GPU 计算实例，支持 Claude Desktop、Cursor 等 AI 工具直接调用。

## 快速开始

### 安装

从 [Releases](https://gitee.com/btc8/matpool-mcp-server/releases) 下载对应平台的预编译二进制。

或自行构建：

```bash
go build -o matpool-mcp-server .
```

### 登录

```bash
# 使用手机号+密码登录
./matpool-mcp-server login

# 指定 API 地址（私有部署环境）
./matpool-mcp-server login -server https://your-api.example.com
```

### 启动 MCP Server

```bash
# stdio 模式（默认，供 Claude Desktop 等使用）
./matpool-mcp-server
```

## MCP Tools

| Tool | 说明 |
|------|------|
| `list_machines` | 查询可用机器资源列表（GPU/CPU/NPU 型号、可用数量、价格、硬件配置） |
| `list_images` | 查询可用镜像列表（指定机器下可用的 OS/框架镜像） |
| `list_gpu_instances` | 查询 GPU 实例列表（分页、状态筛选、关键词搜索，含连接信息和 SSH 凭据） |
| `get_node_status` | 查询实例详细状态（含 IP、端口映射、SSH 凭据、GPU、挂载信息等） |
| `create_node` | 创建新 GPU 实例 |
| `delete_node` | 释放 GPU 实例（可选自动快照） |
| `get_billing` | 查询账单列表 |
| `get_node_bill` | 查询指定实例的账单详情 |

### 连接信息展示

`list_gpu_instances` 和 `get_node_status` 的输出包含完整的连接信息：

- **SSH 端口**：显示 SSH 连接地址（如 `SSH: ssh://192.168.80.9:41999`）
- **非 SSH 端口**：显示原端口与连接 URL 的映射（如 `8888: http://192.168.80.9:34319?token=xxx`）
- **SSH 登录凭据**：显示用户名和密码（从 `sshAuths` 中提取）

### Tool 参数示例

**list_gpu_instances**
```json
{
  "page": 1,
  "per_page": 20,
  "statuses": "2",
  "keywords": ""
}
```
statuses 状态码：1=Pending, 2=Running, 3=Exited, 5=Paused

**create_node**
```json
{
  "agent_id": 100,
  "image_id": 50,
  "hardware_qty": 1,
  "machine_category": 0,
  "meta_key": "my-training-job",
  "envs": "PYTHONPATH=/app;BATCH_SIZE=32",
  "cmd": "python train.py"
}
```
machine_category: 0=GPU, 1=CPU, 2=VGPU, 3=NPU

**delete_node**
```json
{
  "id": "wJ11GP",
  "snapshot_required": false
}
```

## 认证

MCP Server 支持三种认证方式（优先级从高到低）：

1. **环境变量** `MATPOOL_API_TOKEN` — CI/CD 场景
2. **本地文件** `~/.matpool/mcp-token.json` — 通过 `login` 命令保存
3. **命令行参数** `matpool-mcp-server serve <token>`

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MATPOOL_API_TOKEN` | API Token | - |
| `MATPOOL_API_BASE_URL` | API 地址（最高优先级） | - |
| `MATPOOL_ENV` | 运行环境：`dev`/`test` → alpha，`prod` 或未设置 → 正式环境 | `prod` |

默认 API 地址根据环境自动选择：
- `prod`/`production` 或未设置 `MATPOOL_ENV`：`https://matpool.com/api`（生产环境，默认）
- `dev`/`test`/`alpha`：`https://alpha.matpool.com/api`

使用示例：
```bash
# 生产环境（默认）
matpool-mcp-server login

# 开发/测试环境
MATPOOL_ENV=dev matpool-mcp-server login

# 自定义 API 地址
MATPOOL_API_BASE_URL=https://custom.api.com matpool-mcp-server serve
```

## AI 工具集成

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "matpool": {
      "command": "/path/to/matpool-mcp-server",
      "args": []
    }
  }
}
```

或使用环境变量认证：

```json
{
  "mcpServers": {
    "matpool": {
      "command": "/path/to/matpool-mcp-server",
      "args": [],
      "env": {
        "MATPOOL_API_TOKEN": "your-jwt-token",
        "MATPOOL_ENV": "dev"
      }
    }
  }
}
```

### Cursor

在 Cursor Settings → MCP 中添加同样的配置。

### MCP Inspector

使用 MCP Inspector 调试和验证：

```bash
npx @modelcontextprotocol/inspector /path/to/matpool-mcp-server
```

## 项目结构

```
matpool-mcp-server/
├── main.go          # 入口：CLI (login/serve/help) + MCP Server 启动
├── client.go        # HTTP 客户端、API 类型定义、认证逻辑
├── tools.go         # 8 个 MCP Tools 注册与实现
├── tools_test.go    # 单元测试
├── debug_log.go     # 调试日志
├── go.mod           # Go 模块定义
└── README.md        # 本文档
```

## 技术栈

- Go 1.25
- [mcp-go](https://github.com/mark3labs/mcp-go) — MCP 协议 SDK
- stdio transport（标准输入/输出通信）

## 错误处理

MCP Server 对 MatPool API 返回的错误做了分类处理：

| 错误类型 | 处理方式 |
|---------|---------|
| 401 Unauthorized | 提示 Token 过期，建议重新登录 |
| 403 Forbidden | 提示权限不足 |
| 429 Too Many Requests | 提示请求过于频繁 |
| 业务错误码 (code != 0) | 返回原始错误消息 |
| 网络错误 | 提示检查网络连接 |

## License

MIT