🚀 phospho-mcp-server

phospho 的官方 MCP 服务器。本项目实现了一个面向 phosphobot 的 模型上下文协议（Model Context Protocol，MCP） 服务器，支持通过自然语言与实体机器人进行交互和控制。它提供了执行动作（如拾取物体）和从摄像头流式传输图像的工具。本项目基于 mcp 构建，专为 Claude 定制。

✨ 主要特性

• 摄像头流：获取当前网络摄像头的帧。
• 回放工具：从数据集中触发机器人动作（如拾取香蕉）。
• phosphobot 包装器：管理本地 API 进程和通信。

🚀 快速开始

1. 安装并运行 phosphobot

phosphobot 是一款 开源 软件，可用于控制机器人、记录数据、训练和使用 VLA（视觉语言动作模型）。

运行以下命令安装 phosphobot：

# macOS
curl -fsSL https://raw.githubusercontent.com/phospho-app/phosphobot/main/install.sh | bash

# Linux
curl -fsSL https://raw.githubusercontent.com/phospho-app/phosphobot/main/install.sh | sudo bash

# Windows
powershell -ExecutionPolicy ByPass -Command "irm https://raw.githubusercontent.com/phospho-app/phosphobot/main/install.ps1 | iex"

运行 phosphobot 服务器：

phosphobot run

2. 在 Claude Desktop 中安装 MCP 服务器

确保已安装 Claude desktop。

使用 uv 按以下方式安装 phospho-mcp-server：

curl -LsSf https://astral.sh/uv/install.sh | sh # 在 MacOs 或 Linux 上安装 uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # 在 Windows 上

# 克隆仓库
git clone https://github.com/phospho-app/phospho-mcp-server.git

# 安装服务器
cd phospho-mcp-server/phospho-mcp-server
uv run mcp install server.py

这将：

• 以 phospho 名称启动 MCP 服务器。
• 注册所有工具。

现在，打开 Claude desktop，你应该能在工具列表中看到 phospho MCP 服务器。

📚 详细文档

工作原理

该服务器通过其 REST API（默认 http://localhost:80）与 phosphobot 的本地实例进行通信。

• /frames → 图像流
• /recording/play → 从数据集中触发回放

所有调用都通过 tools/phosphobot.py 进行包装。如果你在不同端口上运行 phosphobot，则需要修改基本 URL。

开发与测试

要使用 MCP 检查器测试你的服务器，请运行：

uv run mcp dev server.py

从 Claude 调用摄像头

提问：

“我的桌子上有什么？”

Claude 将调用：

{
  "tool": "get_camera_frame"
}

从 Claude 触发回放

提问：

“捡起香蕉”

Claude 将调用：

{
  "tool": "pickup_object",
  "args": { "name": "banana" }
}

工具说明

pickup_object

启动回放片段以模拟物体操作。

@mcp.tool()
def pickup_object(name: Literal["banana", "black circle", "green cross"]) -> str

• 根据物体名称启动预录制的片段。

get_camera_frame

从 phosphobot 的摄像头捕获 JPEG 图像。

@mcp.tool()
def get_camera_frame() -> Image

• 使用本地 phosphobot API (/frames)。
• 返回 base64 编码的 JPEG 图像。

架构

phospho-mcp-server/
│
├── server.py              # 带有工具的 MCP 服务器（FastMCP）
├── tools/
│   ├── phosphobot.py      # phosphobot 进程和 API 的包装器
│   └── replay_api.py      # 启动回放的工具
├── pyproject.toml         # 项目配置
└── README.md              # 本文件

PhosphoClient 类用于管理 phosphobot 进程的生命周期，并向其本地 API 发送 GET/POST 请求。

📖 参考资料

• 模型上下文协议
• phosphobot