技术文档摘要

phospho-mcp-server

phospho 的官方 MCP 服务器

此仓库实现了一个用于 phosphobot 的 模型上下文协议（MCP） 服务器，支持自然语言交互并控制物理机器人。它提供了执行动作（例如拾取物体）和从摄像头流传输图像的工具。

使用 mcp 构建，并针对 Claude 进行了定制。

https://github.com/user-attachments/assets/2d91f716-c581-4c36-94ab-cc5a94001468

特性

• 摄像头流：获取当前的网络摄像头帧
• 回放工具：触发来自数据集的机器人动作（例如拾起香蕉）
• 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/phphospho-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