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.

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:

Variable	Description
RIKKAHUB_WEB_PASSWORD	RikkaHub Web access password
RIKKAHUB_WEB_URL	Optional explicit RikkaHub Web base URL
RIKKAHUB_WEB_PORT	RikkaHub Web port, default 8080
RIKKAHUB_LAST_IP_FILE	Optional last-successful-IP state file
RIKKAHUB_HISTORY_RUN_MODE	stdio or http
RIKKAHUB_HISTORY_HOST	MCP bind address, default 0.0.0.0 in HTTP mode
RIKKAHUB_HISTORY_PORT	MCP port, default 8766
RIKKAHUB_HISTORY_TOKEN	Bearer token protecting the MCP endpoint
RIKKAHUB_HISTORY_ALLOWED_HOSTS	Comma-separated allowed Host headers, e.g. 192.168.0.10:8766
RIKKAHUB_HISTORY_ALLOWED_ORIGINS	Comma-separated allowed Origins

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