RikkaHub History MCP

A read-only MCP bridge for searching conversations from the official RikkaHub app through its Web API. It does not require a modified APK, root access, or Room database migration.

Features

• recent_conversations — list recent conversations with lightweight metadata.

• search_conversations — use RikkaHub's built-in full-text index.

• get_conversation_context — read a bounded window around a search hit.

• Reads only the currently selected message branch.

• Returns USER/ASSISTANT text only; reasoning, tool calls/results, and attachments are omitted.

• Resolves rikkahub.local with mDNS, so a phone DHCP address change normally needs no reconfiguration.

• Automatically refreshes RikkaHub's Web JWT.

• Streamable HTTP mode can be protected with a separate Bearer token.

Related MCP server: reddit-mcp

Requirements

• Python 3.10+

• RikkaHub Web Server enabled and reachable on the same LAN

• RikkaHub Web JWT/password enabled (recommended)

Install

python -m venv .venv
# Windows
.venv\Scripts\python -m pip install -e .
# Linux/macOS
.venv/bin/python -m pip install -e .

Configure RikkaHub Web

In RikkaHub, enable the Web Server and set an access password. The default Web port is 8080.

The bridge first tries:

http://rikkahub.local:8080

It re-resolves mDNS after failures and can retain the last successful phone IP as a short-lived fallback.

Run with Streamable HTTP

Copy start_http.example.ps1 to the ignored start_http.ps1, then replace its placeholders. Alternatively, set the variables from .env.example in your process environment.

Important variables:

Start:

.\start_http.ps1

Then configure RikkaHub MCP:

Transport: Streamable HTTP
URL: http://<computer-lan-ip>:8766/mcp
Header: Authorization: Bearer <RIKKAHUB_HISTORY_TOKEN>

RIKKAHUB_HISTORY_ALLOWED_HOSTS must include the host and port used in that URL. DNS rebinding protection remains enabled.

STDIO mode

RIKKAHUB_WEB_PASSWORD=... rikkahub-history-mcp

STDIO is the default when RIKKAHUB_HISTORY_RUN_MODE is not set.

Security

• The MCP tools are read-only.

• Do not commit start_http.ps1, .env, passwords, JWTs, or Bearer tokens.

• Bind to a private LAN only and restrict the port with a host firewall.

• The official RikkaHub Web API itself includes write endpoints; this bridge deliberately exposes none of them.

License

MIT