Ricoberry MCP Server (ricoberry-mcp)

Universal Model Context Protocol (MCP) server for the Ricoberry Knowledge Studio. Enables AI assistants (Claude, Cursor, Google Antigravity, Gemini, ChatGPT) to programmatically generate, validate, store, and hot-swap interactive quizzes and study bundles into the Ricoberry desktop application.

Features

• Automated Quiz Creation & Validation: Generates, validates, and stores rich structured quiz sets with strict schema compliance, multiple question types (Single Choice, Multi-Select, True/False, Fill-in-Blank, Matching, Ordered sequence), and pedagogical quality rubrics.

• Instant Hot-Swapping via Local REST (Port 41789): Communicates directly with Ricoberry's local REST API (http://127.0.0.1:41789) to hot-swap generated quizzes into an active window without restarting the app (returns "status": "hot_swapped").

• Process Auto-Spawning & Readiness Polling: If the Ricoberry desktop application is not running when a quiz is created or loaded, the server automatically launches the canonical Debug binary or installed Ricoberry.exe with the target quiz loaded on startup (returns "status": "launched_and_loaded"). launch_in_app is enabled by default (true).

• Bundle & Course Archive Management: Export and import compressed .rcb course bundles containing quiz sets and metadata.

• Learning Analytics & Insights: Access student performance analytics, study history from history.json, weak spot detection, and spaced-repetition metrics.

• Zero External Runtime Dependencies: Built entirely using Python 3.10+ standard libraries (urllib, json, sqlite3, zipfile, pathlib).

Related MCP server: MCPaeroedu

MCP Tools Provided

Installation & Running

Option 1: Running with uvx (Recommended)

No installation required if you have uv installed:

uvx ricoberry-mcp

Option 2: Running from Source / Module

Clone the repository and run:

git clone https://github.com/doc-shashank/ricoberry-mcp.git
cd ricoberry-mcp
python -m mcp_server.server

Option 3: Local Pip Installation

pip install -e .
ricoberry-mcp

Client Configuration

1. Claude Desktop

Add to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Using uvx:

{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}

Using Python module:

{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

2. Cursor

Add to your project's .cursor/mcp.json or global Cursor MCP settings:

{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}

Or using direct Python execution:

{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

3. Google Antigravity

Add to your Antigravity MCP configuration (mcp_config.json):

{
  "mcpServers": {
    "ricoberry": {
      "command": "uvx",
      "args": ["ricoberry-mcp"]
    }
  }
}

Or pointing to the local directory:

{
  "mcpServers": {
    "ricoberry": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "C:/path/to/ricoberry-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Desktop REST Integration (Port 41789)

When creating or loading a quiz, the server interacts with the Ricoberry desktop client:

-1. Active Instance Check: Queries http://127.0.0.1:41789/api/status. -2. Live Hot-Swap: If the app is active, sends POST http://127.0.0.1:41789/api/load-quiz with payload {"path": "<quiz_json_path>"}. The desktop app immediately switches to the new quiz. -3. Cold Start: If the endpoint is unreachable, the launcher automatically discovers Ricoberry.exe across local app data directories or system paths and spawns the process with the quiz path argument. +1. Active Instance Check: Queries http://127.0.0.1:41789/api/status (or the port specified in %LOCALAPPDATA%\Ricoberry\api_port.txt). +2. Live Hot-Swap: If the app is active, dispatches POST http://127.0.0.1:<port>/api/load-quiz with payload {"file_path": "<abs_path>"} or {"quiz_id": "<id>"} / {"quiz": {...}}. The desktop app brings the window to the foreground and hot-swaps to the new quiz with an interactive start countdown (returns "status": "hot_swapped"). +3. Cold Start (Auto-Launch & Polling): If the app is not running, the launcher automatically discovers the canonical Debug binary (Desktop\bin\x64\Debug\net8.0-windows10.0.19041.0\win-x64\Ricoberry.exe) or installed binary, launches Ricoberry.exe with the quiz path argument, and polls get_active_api_port() until the application's REST service is ready and verified (returns "status": "launched_and_loaded").

File Storage Locations

• Quizzes: %LOCALAPPDATA%\Ricoberry\library\*.json (Windows) or ~/.ricoberry/library/*.json (Linux/macOS) -- Bundles: %LOCALAPPDATA%\Ricoberry\bundles\*.ricoberry -- Analytics Database: %LOCALAPPDATA%\Ricoberry\history\analytics.db +- Course Bundles: Compressed .rcb course bundle archives +- Student History & Attempts: %LOCALAPPDATA%\Ricoberry\history.json

Development

# Clone the repository
git clone https://github.com/doc-shashank/ricoberry-mcp.git
cd ricoberry-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install editable
pip install -e .

# Run the server on stdio
ricoberry-mcp

License

MIT License. Copyright (c) 2026 Quartz Technologies.