IvoryOS MCP server

Serve as a robot control interface using IvoryOS and Model Context Protocol (MCP) to design, manage workflows, and interact with the current hardware/software execution layer.

🧩 One-click install in Claude Desktop (desktop extension)

1. Download ivoryos-mcp-<version>.mcpb.
2. Double-click it (or drag it into Claude Desktop, or Settings → Extensions → Advanced settings → Install Extension…).
3. Fill in your ivoryOS URL, username and password, then enable the extension.

Claude Desktop sets up Python and the dependencies itself; nothing else to install. The extension runs on your computer, so it only needs to reach ivoryOS on your network.

To build the .mcpb (from this repo, needs Node.js):

npx @anthropic-ai/mcpb pack . ivoryos-mcp-<version>.mcpb

Keep version in manifest.json in sync with pyproject.toml. .mcpbignore keeps .env and build files out of the bundle.

🚀 Quickstart with Claude Desktop (manual config)

Install uv. Open up the configuration file, and add IvoryOS MCP config.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "IvoryOS MCP": {
      "command": "uvx",
      "args": [
        "ivoryos-mcp"
      ],
      "env": {
        "IVORYOS_URL": "http://127.0.0.1:8000/ivoryos",
        "IVORYOS_USERNAME": "<IVORYOS_USERNAME>",
        "IVORYOS_PASSWORD": "<IVORYOS_PASSWORD>"
      }
    }
  }
}

📦 Installation

Install uv.

1. Clone the Repository

git clone https://gitlab.com/heingroup/ivoryos-mpc
cd ivoryos-mcp

2. Install dependencies

When using IDE (e.g. PyCharm), the uv environment might be configured, you can skip this section.

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r uv.lock

⚙️ Configuration

Option 1: in .env, change ivoryOS url and login credentials.

IVORYOS_URL=http://127.0.0.1:8000/ivoryos
IVORYOS_USERNAME=admin
IVORYOS_PASSWORD=admin

Option 2: In ivoryos_mcp/server.py, change ivoryOS url and login credentials.

url = "http://127.0.0.1:8000/ivoryos"
login_data = {
    "username": "admin",
    "password": "admin",
}

🚀 Install the server (in Claude Desktop)

mcp install ivoryos_mcp/server.py

✨ Features

⚠️ ℹ️ are resources, but decorated as tool due to the current issue with MCP Python SDK and Claude Desktop integration.
It's recommended to only use allow always for ℹ️ tasks
and use allow once for 🤖 tasks. These tasks will trigger actual actions on your hosted Python code.

🧪 Examples

The example prompt uses the abstract SDL example.

Platform info

Load prebuilt workflow script