# Phospho Mcp Server

> phospho's official MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-phospho-app-phospho-mcp-server`
- **Verified:** Pending review
- **Seller:** [phospho-app](https://agentstack.voostack.com/s/phospho-app)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [phospho-app](https://github.com/phospho-app)
- **Source:** https://github.com/phospho-app/phospho-mcp-server

## Install

```sh
agentstack add mcp-phospho-app-phospho-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# phospho-mcp-server
[phospho](https://docs.phospho.ai/)'s official MCP Server

This repository implements a **Model Context Protocol (MCP)** server for **phosphobot**, enabling natural language interaction and control over a physical robot. It exposes tools to execute actions (e.g. pick up an object) and stream images from cameras.

Built using [mcp](https://github.com/modelcontextprotocol/python-sdk) and tailored for Claude. 

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

## Features

- **Camera stream**: retrieves the current webcam frame
- **Replay tool**: triggers a robot action from a dataset (e.g. pick up banana)
- **phosphobot wrapper**: manages local API processes and communication

## Getting Started

### 1. Install and run phosphobot 

[phosphobot](https://docs.phospho.ai) is an [open source](https://github.com/phospho-app/phosphobot) software that lets you control robots, record data, train and use VLA (vision language action models).

Run this to install phosphobot:
```bash 
#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"
```

Run the phosphobot server:
```bash
phosphobot run
```

### 2. Install the MCP server in Claude Desktop

Make sure [Claude desktop](https://support.anthropic.com/en/articles/10065433-installing-claude-for-desktop) is installed. 

Install phospho-mcp-server this way using [uv](https://docs.astral.sh/uv/getting-started/installation/):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh # Install uv on MacOs or Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # On Windows

# Clone repo
git clone https://github.com/phospho-app/phospho-mcp-server.git

# Install the server
cd phospho-mcp-server/phospho-mcp-server
uv run mcp install server.py
```

This will:

* Boot the MCP server under the name `phospho`
* Register all tools with 

Now, open Claude desktop. You should see the phospho MCP server listed along the tools.  

## How it works

The server speaks to a local instance of [phosphobot](https://robots.phospho.ai/) through its REST API (default `http://localhost:80`).

* `/frames` → image feed
* `/recording/play` → trigger replay from dataset

All calls are wrapped via `tools/phosphobot.py`. If you run phosphobot on a different port, you need to modify the base URL.

---

## Development and testing

To test your server with the MCP inspector, run:
```bash 
uv run mcp dev server.py
```

### Camera from Claude 

Ask:

> “What’s on my desk?”

Claude will call:

```json
{
  "tool": "get_camera_frame"
}
```

### Replay from Claude 

Ask:

> “Pick up the banana”

Claude will call:

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

---

## Tools

### `pickup_object`

> Launches a replay episode to simulate object manipulation.

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

* Launches a pre-recorded episode based on the object name.

### `get_camera_frame`

> Captures a JPEG image from phosphobot's camera.

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

* Uses the local phosphobot API (`/frames`)
* Returns a base64-encoded JPEG image

---

## Architecture

```bash
phospho-mcp-server/
│
├── server.py              # MCP server (FastMCP) with tools
├── tools/
│   ├── phosphobot.py      # Wrapper for phosphobot process and API
│   └── replay_api.py      # Tool to launch a replay
├── pyproject.toml         # Project configuration
└── README.md              # This file
```

The `PhosphoClient` class is used to manage the `phosphobot` process lifecycle, and send GET/POST requests to its local API.

---

## References

* [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)
* [phosphobot](https://docs.phospho.ai/installation)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [phospho-app](https://github.com/phospho-app)
- **Source:** [phospho-app/phospho-mcp-server](https://github.com/phospho-app/phospho-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-phospho-app-phospho-mcp-server
- Seller: https://agentstack.voostack.com/s/phospho-app
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.