inoreader-remote-mcp

A remote MCP server for Inoreader: read, mark and manage your feeds from Claude — web, desktop and mobile — through a custom connector. Self-hosted, single user, one Docker container, no database.

Not affiliated with Inoreader. This is an independent project using the public Inoreader API. Inoreader is a trademark of its owner.

What it does

Ten tools, each costing one Inoreader API call (Inoreader allows about a hundred requests per day per zone on the Pro plan):

Articles come back short: id, title, URL, feed name, publication date, crawlTimeMsec and a plain-text summary cut at 500 characters. Pagination is handed to Claude: a page carries a continuation value, passed back for the next page. When a daily quota is reached, Claude receives an explicit message with the time until the counters reset.

Tool descriptions are written in French.

Related MCP server: RSS Feed MCP Server

How it works

Claude ──HTTPS──▶ reverse proxy ──▶ inoreader-remote-mcp :8000 ──▶ Inoreader API
                                     ├── /mcp            MCP, Streamable HTTP, bearer token
                                     ├── OAuth 2.1 server for Claude (/register, /authorize, /token…)
                                     ├── /oauth/consent  consent screen (admin password)
                                     └── /oauth/inoreader/start|callback  one-time Inoreader authorisation

Two OAuth flows, independent:

• Claude → this server. Claude's custom connectors require OAuth. The server is its own authorisation server: Claude registers itself, you approve on a consent screen with the admin password, Claude gets an access token (1 h) and a rotating refresh token (60 days).

• This server → Inoreader. Done once, in your browser. The Inoreader tokens are stored on the volume and refreshed automatically.

Everything persistent is two JSON files in DATA_DIR, written atomically with 0600 permissions: inoreader_tokens.json and oauth.json (Claude's clients and token digests — tokens are never stored in clear).

Requirements

• An Inoreader account with API access (Inoreader Pro, see their developer terms).

• A host running Docker, reachable over HTTPS under a public hostname (Claude connects from the internet), behind a reverse proxy that terminates TLS.

• Claude with custom connectors available on your plan.

1. Register an Inoreader app

In Inoreader: Preferences → Developer → Register an application (use a dedicated app for this server, so that its quota is not shared with other tools).

• Redirect URI: https://inoreader.example.com/oauth/inoreader/callback (your public hostname, exactly).

• Scope: Read and write.

Note the App ID and App Key.

2. Configure

Copy .env.example to .env next to docker-compose.yml, then chmod 600 .env:

Left empty, ADMIN_PASSWORD closes the admin routes rather than opening them.

3. Deploy

mkdir -p data          # before the first start, so that it belongs to you, not root
docker compose pull
docker compose up -d
docker compose logs -f # expect: Uvicorn running on http://0.0.0.0:8000

The provided docker-compose.yml publishes no port: the container joins an external Docker network named proxy, shared with the reverse proxy. Adjust it to your setup. The container runs as UID 1000 / GID 100.

Reverse proxy: forward https://inoreader.example.com to http://inoreader-remote-mcp:8000. MCP responses are streamed, so disable response buffering. With nginx (or Nginx Proxy Manager, Advanced tab):

proxy_buffering off;
proxy_read_timeout 300s;

Check: curl https://inoreader.example.com/health returns {"status":"ok",…}.

4. Authorise Inoreader (once)

Open https://inoreader.example.com/oauth/inoreader/start in a browser. Log in with any user name and the ADMIN_PASSWORD, approve on Inoreader, and you land on « Inoreader est connecté ». data/inoreader_tokens.json now exists.

To bind another Inoreader account, or after revoking the app in Inoreader, run it again.

5. Add the connector in Claude

In Claude: Settings → Connectors → Add custom connector.

• Name: Inoreader

• URL: https://inoreader.example.com/mcp

• Leave the advanced OAuth client fields empty: Claude registers itself.

Click Connect. The consent screen shows the client name and where the code will be sent — it must be claude.ai; refuse otherwise. Type the admin password and approve. The connector is then available on web, desktop and mobile.

Try: « Combien d'articles non lus ai-je sur Inoreader ? »

Updating

The CI publishes ghcr.io/ctricot/inoreader-remote-mcp:latest and :sha-<commit> on every push to main.

• Automatic: the compose file carries the label com.centurylinklabs.watchtower.enable=true; a Watchtower running with WATCHTOWER_LABEL_ENABLE=true pulls each new image.

• Manual: docker compose pull && docker compose up -d.

• Roll back: IMAGE_TAG=sha-<commit> docker compose up -d.

Tokens survive updates: Claude stays connected, Inoreader stays authorised.

Security notes

• The admin password is the only key: it authorises Inoreader and approves Claude clients. Wrong attempts are slowed down; still, use a long random value.

• The consent password is typed into a form, never sent as HTTP Basic, so a forged request from another site cannot approve a client.

• data/ holds the Inoreader refresh token: keep it private and back it up. Deleting data/oauth.json disconnects every Claude client.

Development

uv sync
uv run pytest       # Inoreader is mocked with respx, no network
uv run ruff check && uv run ruff format --check
ADMIN_PASSWORD=dev uv run python -m inoreader_remote_mcp   # http://localhost:8000

License

MIT