WROLPi MCP Server

An MCP server that lets an LLM (Claude Desktop, Claude Code, or any MCP client) search and read the contents of your WROLPi: videos and their captions, archived web pages, ebooks and documents, Zim encyclopedias, maps, tags, inventories, and the download queue.

Every tool only reads, except upgrade_wrolpi, which your MCP client asks you to approve. The server runs on your computer, not on the WROLPi, and talks to the WROLPi's normal HTTP API over your network. Every result carries a link back into the WROLPi web app.

Requirements

• A WROLPi reachable from this computer (for example https://wrolpi.local:8443).

• uv (recommended) or Python 3.11+ with pipx.

Related MCP server: ZIM MCP Server

Install

Install it as a persistent command. A WROLPi is meant to work offline, and this is the install that starts without the Internet:

uv tool install git+https://github.com/wrolpi/mcp
# or
pipx install git+https://github.com/wrolpi/mcp

To update later:

uv tool upgrade wrolpi-mcp
# or
pipx upgrade wrolpi-mcp

then restart the MCP client (or toggle the server off and on) so it relaunches the new version.

You can also run it without installing, straight from this repository:

uvx --from git+https://github.com/wrolpi/mcp wrolpi-mcp

Avoid this form in a client config: uvx asks GitHub which commit is current on every launch, so the server fails to start whenever the Internet is down (even with uv --offline). Pinning a tag does not help; only a full commit hash (git+https://github.com/wrolpi/mcp@<40-char sha>) starts offline.

Configure

The server reads these environment variables:

Claude Code

claude mcp add wrolpi -e WROLPI_API_URL=https://wrolpi.local:8443 -- wrolpi-mcp

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "wrolpi": {
      "command": "wrolpi-mcp",
      "env": {"WROLPI_API_URL": "https://wrolpi.local:8443"}
    }
  }
}

Claude Desktop may not see your shell's PATH; if the server does not start, use the full path to wrolpi-mcp (which wrolpi-mcp).

LM Studio

LM Studio 0.3.17 or newer can run MCP servers. Open a chat, switch to the Program tab in the right-hand sidebar, click Install > Edit mcp.json, and add the wrolpi entry (the file is ~/.lmstudio/mcp.json, or %USERPROFILE%\.lmstudio\mcp.json on Windows):

{
  "mcpServers": {
    "wrolpi": {
      "command": "wrolpi-mcp",
      "env": {"WROLPI_API_URL": "https://wrolpi.local:8443"}
    }
  }
}

Save the file, then turn the wrolpi server on in the Program tab for the chat. The first tool call opens a confirmation dialog where you can allow it once or always.

Notes:

• Use a model that supports tool calling (LM Studio marks them with a tool icon). Small models can emit tool calls but get unreliable as the tool list grows.

• LM Studio is a GUI app and may not see the PATH of your shell. If the server fails to start with a "command not found" error, put the full path to wrolpi-mcp in command (which wrolpi-mcp on macOS/Linux, where wrolpi-mcp on Windows).

Tools

Upgrades

upgrade_wrolpi asks the WROLPi's Controller to upgrade to the newest code of a branch, exactly like Upgrade on the Controller page. Omit the branch to upgrade the branch the WROLPi already runs. The upgrade takes several minutes and restarts every WROLPi service, so the other tools fail meanwhile; get_upgrade_status reports progress from the Controller, which stays up. A WROLPi running in Docker cannot upgrade itself.

Database queries (advanced)

query_database runs read-only SQL (SQLite) against the WROLPi's database, for questions the other tools cannot answer ("which channels have the most unwatched videos?"). The WROLPi refuses these until you opt in, because WROLPi's API has no login: anyone who can reach the WROLPi could read the whole database, including viewing history. There is no switch for it in Settings. To enable it, add this to config/wrolpi.yaml in the media directory:

allow_database_query: true

then click Import for wrolpi.yaml on the WROLPi's Configs page (or restart the WROLPi). To turn it off again, set it to false and import again; deleting the line has no effect until the WROLPi restarts.

Queries cannot change anything: the WROLPi opens the database read-only and refuses any statement other than a read. Each query is stopped after 10 seconds, returns at most 1000 rows to the model, and long text values are cut short.

Troubleshooting

Every tool fails, or a search fails and then everything after it does. The usual cause is one slow request. A deep=True search or a search across every Zim can take minutes on a Raspberry Pi; if the server gives up first, the WROLPi keeps working on the abandoned request and the next calls queue behind it. Since 0.1.1 the model is told exactly this (and how to retry) instead of a bare "Error executing tool". If it still happens, raise WROLPI_TIMEOUT, or ask for title-only searches.

The model never sees an error message, only "Error executing tool". Upgrade the server: that is how versions before 0.1.1 reported a timeout. uv tool upgrade wrolpi-mcp (or pipx upgrade wrolpi-mcp), then restart the client. If your config runs uvx --from git+..., clear its cache instead so it fetches the latest: uv cache clean wrolpi-mcp.

The server will not start while the Internet is down. Your config runs it through uvx --from git+https://github.com/wrolpi/mcp, which must contact GitHub on every launch. Switch to the persistent install above and set "command": "wrolpi-mcp".

"Could not reach the WROLPi". WROLPI_API_URL must be the address you type in a browser, including https:// and the port (https://wrolpi.local:8443). The server's log goes to the MCP client's log (LM Studio: Developer > Logs; Claude Desktop: ~/Library/Logs/Claude/mcp*.log).

Development

git clone https://github.com/wrolpi/mcp wrolpi-mcp
cd wrolpi-mcp
uv sync
uv run pytest
# Try the tools interactively in the MCP Inspector:
WROLPI_API_URL=https://wrolpi.local:8443 uv run mcp dev wrolpi_mcp/server.py

tests/test_live.py runs every tool against a real WROLPi when WROLPI_LIVE_URL is set:

WROLPI_LIVE_URL=https://wrolpi.local:8443 uv run pytest tests/test_live.py

License

GPLv3, the same as WROLPi.