inoreader-mcp

MCP server for the Inoreader RSS reader API. Lets Claude help you triage articles, analyze feed health, and manage subscriptions.

Setup

1. Create an Inoreader API application

Go to the Inoreader Developer Portal and create a new application.

• Set the redirect URI to http://localhost:3333/callback

• Note your Client ID and Client Secret

2. Install

This project is not published to npm. The name inoreader-mcp on the npm registry belongs to an unrelated project, so npx inoreader-mcp installs someone else's code. Build it from source instead (Node 24 or newer: the taste index uses node:sqlite):

git clone https://github.com/justmytwospence/inoreader-mcp
cd inoreader-mcp
npm install && npm run build

3. Add to Claude Code

claude mcp add -s user \
  -e INOREADER_CLIENT_ID=your-client-id \
  -e INOREADER_CLIENT_SECRET=your-client-secret \
  inoreader -- node /absolute/path/to/inoreader-mcp/dist/index.js

Or for Claude Desktop, add to your config file:

{
  "mcpServers": {
    "inoreader": {
      "command": "node",
      "args": ["/absolute/path/to/inoreader-mcp/dist/index.js"],
      "env": {
        "INOREADER_CLIENT_ID": "your-client-id",
        "INOREADER_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

4. Authenticate

On first use, ask Claude to call the setup_auth tool. It will give you an OAuth URL to open in your browser. After authorizing, copy the code parameter from the redirect URL and pass it back. Tokens are saved to ~/.config/inoreader-mcp/tokens.json and refresh automatically.

Or run it as a service (Docker)

cp .env.example .env   # fill in the INOREADER_* values
docker compose up -d

The server then speaks Streamable HTTP at http://<host>:8000/mcp (also at /), with a health check at /health, for 2026-07-28 and older session-based clients alike. Running as a service adds two things a stdio process cannot do:

• It receives the OAuth redirect. Set INOREADER_REDIRECT_URI (and the redirect URI on your Inoreader app) to https://<this server>/callback. setup_auth then returns a link; authorize, land on /callback, and the tokens are saved. Nothing to paste.

• It keeps the grant alive. Inoreader's refresh token expires on its own after a couple of weeks unused, so the server refreshes it every INOREADER_KEEPALIVE_HOURS (default 12) and, if NTFY_URL + NTFY_TOPIC are set, pushes an alert when a refresh fails.

Images: ghcr.io/justmytwospence/inoreader-mcp, published for amd64 and arm64 by pushing a vX.Y.Z tag.

Related MCP server: ttrss-mcp

Taste index

An optional, local semantic index of what you saved and valued: find saved items close to a piece of text, and check whether a text repeats something already saved. Similarity measures topical overlap, not quality: it is not a score of whether something is any good.

It is off unless INOREADER_TASTE_INDEX=on, and then adds four tools (33 instead of 29). Stdio users who do not set it are unaffected: the model and node:sqlite are never loaded.

What gets indexed is configuration, not code. INOREADER_TASTE_CONFIG names a JSON file of sources and ordered tiers; nothing about your tags, labels or services is built in. Without a file the index covers what every account has, starred items and highlighted (annotated) items. An example file, for an account that saves to an Archive label, marks the best with Clip, and also keeps Karakeep bookmarks:

{
  "sources": [
    {"name": "archive", "type": "inoreader-stream", "stream": "user/-/label/Archive"},
    {"name": "clip", "type": "inoreader-stream", "stream": "user/-/label/Clip"},
    {"name": "highlights", "type": "inoreader-annotations"},
    {"name": "karakeep", "type": "karakeep", "url_env": "KARAKEEP_API_URL", "key_env": "KARAKEEP_API_KEY", "min_words": 300}
  ],
  "tiers": [
    {"name": "clip", "sources": ["clip"]},
    {"name": "good", "sources": ["clip", "highlights", "karakeep"]},
    {"name": "archive", "sources": ["*"]}
  ],
  "default_tier": "good",
  "novelty_threshold": 0.75
}

• Sources. inoreader-stream: any stream ID (a label, a folder, starred, saved web pages). inoreader-annotations: the annotated stream, keeping each highlight and note. karakeep: your Karakeep bookmarks, for pages saved outside Inoreader (see below). Names are 1-32 characters of letters, digits, _ and -.

• Per-source exclude_domains. Any source may list domains ("exclude_domains": ["github.com"]); a domain also covers its subdomains, and www. is ignored. An item from one of them does not count as a member of that source anywhere (tiers, filters, searches); an item no source counts any more is not searched at all. Applied when the index loads, so changing it needs only a restart: nothing is re-read or re-embedded. taste_index_status reports how many items each source excludes.

• Tiers are ordered narrowest first and list source names; * means all of them. An item is in a tier when any of its sources is listed. default_tier defaults to the last (widest) tier and novelty_threshold to 0.75. The file is validated at start: an unknown source in a tier, a duplicate name or an unknown default_tier stops the server with a message naming the problem. The built-in default has sources starred and highlights, tiers highlights then saved (*), default tier saved.

• Items are keyed by normalized URL (https, no www., no fragment, trailing slash or /amp, no tracking parameters), so the same page saved through different routes is one row carrying several signals, one per source it belongs to. An item is deleted once its last signal is gone.

• Text comes from the stored feed HTML Inoreader already returns (no paid full-text extraction is ever started). One vector per item is embedded from title + opening (~1,200 characters). Items in any tier but the widest also keep their cleaned text (capped at 20k characters) for longer excerpts. A teaser-only feed item falls back to Karakeep's crawl when the URLs match.

• Why Karakeep needs its own source. Inoreader's API reports an item's state only through its categories (read, starred, labels, annotated, ...). Sending an article to Instapaper, Pocket or Karakeep leaves nothing the API can read, and most Karakeep saves never pass through Inoreader. Such signals can only come from the destination's own API. If you want a send counted without one, also tag the item in Inoreader and list that label as an inoreader-stream source.

• Karakeep source. url_env and key_env name the environment variables holding the base URL and an API key; the file itself holds no secrets. Only link bookmarks count. Karakeep's own reader-view classifier decides whether a page is an article (not_readable is skipped, readable kept); where it gives no definite answer (uncertain, unavailable, not yet classified) the page needs at least min_words words (default 300). "use_reader_view": false makes the word count the only test. Checked against Karakeep 0.34.1.

How it runs. Vectors are 384-dimensional (Xenova/bge-small-en-v1.5, 8-bit quantized) in a SQLite file at <INOREADER_CONFIG_DIR>/taste/index.sqlite, searched exactly in memory (a few milliseconds for thousands of items). The model runs in a worker thread, loads on first use and exits after 10 idle minutes, so steady state stays small. The index is rebuildable: a changed model/schema or a damaged file starts it over (a rebuild costs about 15 Zone 1 reads). Ideas and items are both embedded as passages, without BGE's query prefix.

Syncing. In HTTP mode the 12-hour keepalive job refreshes the tokens and then syncs the index in the same tick; the first tick (60 seconds after start) is the backfill. A sync failure never affects the refresh or its ntfy alert: it is logged and shown by taste_index_status. In stdio mode there is no scheduler, only sync_taste_index. Disabling the keepalive (INOREADER_KEEPALIVE_HOURS=0) also disables the scheduled sync.

A sync costs one Zone 1 read of stream membership per 10,000 members of each stream source (which also catches removals), one content read per 20 new items, and one annotations read per 100 highlighted items; Karakeep is local and costs no Inoreader reads. A first full build of two streams of ~1,000 items and an annotated stream is about 55 reads (content is read 20 items at a time: a response carries each item's full stored HTML), an incremental sync 3 to 5. A sync keeps 25 reads in reserve (like analyze_feeds) and, if quota is short, does nothing and leaves the index unchanged. A failing source keeps its stored members and is reported; the others still apply. If the model cannot load, items are stored without vectors and the next sync embeds them.

While the index is still building, similar_saved and check_novelty report coverage (sources synced, items indexed) so an empty answer is not mistaken for a real one.

Filters (both tools, all optional, all must pass, applied before ranking and k). They describe the text and where it came from, not whether it is any good; clients combine them for their own purpose, and can filter or rank further on the metadata each result carries.

A prose paragraph is a paragraph of at least 25 words ending in sentence punctuation, counted in the item's opening (its first ~1,200 characters, cut at a sentence end), because the opening is all the index keeps for items in only the widest tier; every item is measured the same way. prose_ratio is the share of the opening's words in such paragraphs. Together they are a coarse article-versus-page test: on a real index, READMEs, product pages, docs and shop pages mostly had 0-1 prose paragraphs or a ratio under 0.6, essays 2 or more and 0.6 or more, but about half the GitHub READMEs still passed (pair it with exclude_domains) and a few essays with unusual markup did not.

What the novelty score can and cannot tell. Measured on a real index of about 4,000 items: paraphrases of an archived essay's thesis scored 0.58 to 0.78 against it, while ideas on the same topic making a different point scored 0.62 to 0.76. Similarity separates related from unrelated well, but not same point from same topic. A high novelty_threshold (about 0.78) makes close rare and reliable; anything below it may still be the same point, so a client that cares should read the nearest items and their similarity rather than the verdict alone.

In the image, set INOREADER_TASTE_INDEX=on and, for a config file, mount it and point INOREADER_TASTE_CONFIG at it. The model files are in the image (/app/models, pinned and checksummed), and the index lives in the /data volume under taste/. The image is about 390 MB.

Resources, measured in the image (docker run --rm --memory 1g --entrypoint node <image> dist/taste/bench.js embeds 1,500 synthetic items of 1,200 characters and prints peak RSS and timing): peak RSS about 420 MB while embedding items of that size (about 300 tokens), about 650 MB for texts that fill the model's 512 tokens, 0.16 s per item on one thread (a first build of ~1,300 items takes about 3 to 4 minutes, in a worker thread, so the server stays responsive). After 10 idle minutes the worker exits and most of that memory is returned: the bench process falls from its 420 MB peak to between 115 and 165 MB, against a baseline of 45 to 80 MB (the rest is allocator slack, which MALLOC_TRIM_THRESHOLD_ in the image keeps small). A 1 GB memory limit is a comfortable ceiling; one CPU and INOREADER_TASTE_THREADS=1 are enough.

Feed priority

An optional, single-process HTTP-only feature for maintaining a folder of priority sources. Set INOREADER_PRIORITY_CONFIG to a JSON file of named profiles. Without it, no priority tools or local priority state are loaded; existing tools remain available. A profile configures its folder, explicit positive streams, excluded topic folders, Bayesian evidence requirements and calibration policy. Folder membership is additive: feeds keep their existing topic folders. A minimal shadow configuration is:

{
  "profiles": [{
    "name": "priority",
    "folder": "Priority",
    "positive_streams": ["user/-/state/com.google/starred"],
    "excluded_topic_folders": ["Priority"],
    "auto_add_enabled": false,
    "promotion_probability": null
  }]
}

Defaults are a 12-month historical window, strength-10 priors, 20 mature observations, five positive engagements, seven maturation days, and the benchmark max(0.20, 2 * topic_baseline). Add only actual positive article-tag streams to the allowlist; collection verifies their type. With MCP_TRANSPORT=http and INOREADER_PRIORITY_CONFIG pointing to the file, start explicitly using refresh_feed_priority({profile: "priority", start_new: true}), then resume by the returned snapshot_id. get_feed_priority({profile: "priority"}) reads local status. These operations collect evidence but do not populate the folder.

The signal is explicit starred/tagged engagement, not the ordinary read flag. Operational folders, automated recommendation tags and negative feedback are not positive signals. IDs identify articles: differing saved-stream dates are deduplicated rather than rejected, and feed/cohort dates determine exposure and maturity. Historical rates describe retrievable history: retention and unknown subscription dates can bias them. Calibrated additions require complete, mature forward-observed evidence. Explicitly reviewed provisional mode instead uses mature historical evidence with the same exact category-pooled Beta–Binomial model; its cutoff is not empirically calibrated.

A newly configured profile starts in shadow mode: automatic additions are disabled, there is no default promotion-confidence cutoff, and no membership is seeded. The default promotion_mode: "calibrated" retains prospective calibration and two-week confirmation. An operator can explicitly choose promotion_mode: "provisional" with a matching provisional_review acknowledging the lack of empirical calibration and a probability cutoff of at least 0.95. That mode can act after one complete fresh snapshot, using at least 20 historical articles aged seven days and five positive engagements. It keeps the same topic-relative benchmark and five-addition limits. Set the review's config_hash from get_feed_priority, with matching probability and an ISO reviewed_at; do not fabricate a calibration review. activation reports the mode and readiness separately from calibration. A posterior probability is not itself empirical calibration. Missing, stale, partial or retention-inconsistent evidence cannot authorize additions. The first bounded scan may take several days; provisional mode does not bypass it.

There is no automatic removal or unsubscribe action. Removal suggestions are advisory; pin and remove require the user's explicit instruction. remove means removal from the configured folder only. A durable exclusion is recorded before the remote edit, so the next scan cannot silently add the source back. Pins, exclusions, pending outcomes and replacement identities live in <INOREADER_CONFIG_DIR>/priorities/, shared by clients. A malformed preference file fails closed rather than discarding the user's decisions.

Snapshots are explicit local records with collection timestamps, coverage and configuration identity. Status and calibration load the most recent eight completed weekly snapshots plus explicitly requested or active evidence; older snapshots remain on disk and can be read by ID. This bounds the working set without deleting user decisions or archived evidence. Snapshots do not restore the hidden response caching once removed from ordinary API reads. An ambiguous membership edit is reconciled from server state before another write; never blindly replay a timed-out edit. Manual membership changes between observations can only be detected when a subsequent complete read observes them; a remove-and-readd entirely between reads leaves no API history to reconstruct.

Run a configured feature behind one HTTP process, not independent stdio writers or replicas. The profile/decision gates are safeguards, not a separate authentication boundary: MCP tool annotations and a client's claim of human approval are not proof of authorization.

Resources

Context that MCP clients can read directly without tool calls.

Article content template: inoreader://articles/{article_id}/content?max_chars={max_chars}. Percent-encode the ID and supply a required integer max_chars from 1 to 20000; for example inoreader://articles/123/content?max_chars=8000. Reading it costs one Zone 1 content POST (safe-read retries extra). It returns bounded stored HTML, truncation and provenance, never starts full-text extraction or paid processing. The static usage guide includes these examples for clients that do not list templates or consume initialize instructions. Discovery and prompt retrieval perform no HTTP or account writes; live resource reads use the same authorized API as tools.

Tools

API primitives

Thin wrappers around individual Inoreader API endpoints.

Reading

Subscriptions

Organization

Account

Composite tools

Higher-level workflows that combine multiple API calls or add client-side logic.

Feed management

Saved items

Classifier calibration

Starred articles, saved web pages, and Keep-tagged items are separate, overlapping streams. get_saved_items reads at most 100 items per page per collection; total_count, by_collection and saved_via describe the fetched pages, not the whole account unless complete=true. Resume individual streams with get_articles and the reported continuation; membership may be incomplete while pages remain. count_only in get_saved_web_pages counts one IDs page of at most 10000, with total_is_exact and continuation, not an unconditional account total.

The keep tag (via manage_tags add_tag='keep') protects a page from cleanup without starring it. Use get_saved_web_pages(filter='removable') for pages that are neither starred nor kept.

Z1 = Zone 1 (read), Z2 = Zone 2 (write). Costs above are base requests; safe-read retries are additional attempts. Read inoreader://usage and get_rate_limit_status before expensive work. All 29 default tools (33 with the taste index, plus three when feed priority is configured) explicitly declare all four safety hints; these are advisory, not authorization or approval enforcement. JSON text results are preserved alongside structured data (legacy top-level arrays appear under structuredContent.items). Output schemas are declared and validated for stable ID/saved-union/folder-write shapes.

Prompts

Pre-built workflows that combine resources and tools into guided tasks.

Classifier calibration workflow

If you use Inoreader Intelligence to classify articles as worth reading vs. skippable, the calibration tools let you treat that LLM as a binary classifier and analyze its reliability over time using only data already in Inoreader (no new LLM calls).

1. Configure the prompt

In Inoreader Intelligence settings, create a custom summary prompt:

Summarize this article in 2-3 sentences. Then on new lines, output exactly:

RECOMMENDATION: read | skip
CONFIDENCE: <integer 0-100>

Be conservative — most articles are not worth reading in full. Recommend "read"
only if the article likely contains substantive new information that cannot be
obtained from the summary alone.

Optionally set up an Inoreader automation rule with the "Create summary" action so summaries are auto-generated for new articles in folders you care about.

2. Tag articles after reading

When you finish reading an article, apply one of these tags via manage_tags (forward slashes are part of the label name, not a folder hierarchy):

3. Run the analysis

Call the analyze-classifier prompt periodically (or once verified counts pass ~30). It runs analyze_classifier_calibration once, checks data_summary for sufficient labels and cap flags, then reviews the reliability diagram and diagnostics. It does not repeat the same extraction merely to inventory labels.

4. Optionally audit

If you want to validate that the calibration curve extends below the decision threshold, call recommend_audit_articles. It returns a small batch of recommend-skip articles weighted by where the calibration curve has the most uncertainty. Read them, apply the audit/* tags, and the next analyze_classifier_calibration run will produce a posterior over recall using that data.

Why this is structured this way

This is a selective labels problem: you observe ground truth for articles the LLM recommended (you read them), and not for articles it told you to skip (unless you audit). The calibration curve on the recommended slice is fully identified from observed data — that's the headline product, with per-bin Beta-Binomial posteriors and an isotonically-smoothed monotone curve. Below the decision threshold, behavior is unobserved without audits; that's why the threshold diagnostic only states an upper bound (via monotonicity) and the recall posterior only appears once audit/* tags exist.

Write verification

Every bulk write reads its own result back and reports only what the server confirms.

This exists because of a specific failure. A 42-feed reassign_feeds call returned {"succeeded": 42, "failed": 0} having actually moved 21: eleven feeds had not moved, and fourteen had been added to the destination without being removed from the source — from a single request carrying both a= and r= that Inoreader answered 200. The discrepancy surfaced days later, by reading all 1818 subscriptions back by hand.

Two things allowed it. succeeded counted HTTP 2xx responses rather than applied changes, and by_folder was built from the input map, so it could not represent a shortfall at all. Inoreader also returns 200 "OK" for an edit to a feed that does not exist, so no amount of inspecting the request or its response can establish what happened. Only reading the state back can.

So the bulk tools preflight known worst-case write/verification costs, apply, wait, re-read, reconcile observed shortfalls once, and report. Missing articles/feeds or failed verification are unknown, not permission to replay an ambiguous write:

isError is set whenever verified < intended. Trust verified, never the size of your request. unverified is the bucket the old code reported as success.

Verification is cheap for folder writes — subscription/list returns every feed with its labels in one request, so 4 feeds and 400 cost the same, in the zone that is not scarce. Article tags cost one read per 50.

Rate Limits

Tool descriptions and the static guide include API costs. get_rate_limit_status and inoreader://rate-limits make zero HTTP requests or auth probes, reading persisted observations under ~/.config/inoreader-mcp/rate-limit.json.

Every API fetch attempt, including retries and transport failures, is counted; every response's quota headers are ingested, including 429/5xx. Usage/limit observations are timestamped per zone. Raw headers are distinct from conservative admission estimates for later local attempts or out-of-order responses. Reset/cooldown times are absolute and countdowns age. Missing/expired usage is unknown, not free calls; legacy snapshots without field-level provenance do not authorize quota estimates. Other clients/processes may consume unseen quota. Persistence is best-effort telemetry, not a cross-process lock; admission and the shared four-operation HTTP concurrency cap apply within one process (including public-site discovery and OAuth).

Safe reads alone retry up to four attempts, with jitter and Retry-After; delays over 60 seconds fail with a persisted cooldown instead of sleeping indefinitely. Writes are never blindly replayed after transport loss, 5xx or unexpected bodies. OAuth requests and public-site fetches are separate from Zone 1/2 API counts.

Expensive workflows preflight known headroom and recheck admission on each attempt. analyze_feeds defaults to at most 100 base calls across tags/volume (max_requests up to 500); it and classifier scans leave 25 known requests in reserve. Classifier scans preflight the maximum page budget. Unknown quota still permits bounded work. Preflight is not a reservation: other calls can consume budget before a workflow finishes. Partial results/cap/degraded/error flags must not be treated as full coverage.

Offline checks (no account calls): npm test, npm run typecheck, npm run build. CI and the release image job require these checks. INOREADER_MCP_MODEL_TESTS=1 npm test also runs the real embedding model (set INOREADER_TASTE_MODEL_DIR to a local copy, else it is downloaded): it checks that a paraphrase of an essay's thesis scores at or above 0.75 against it and unrelated text below 0.6.

Do not hardcode a daily limit. This README claimed ~100/zone/day for a long time; the account it was developed against actually reports 2000. Ask the tool.

License

MIT, see LICENSE.