No description
  • TypeScript 87.7%
  • JavaScript 9.5%
  • Nix 1%
  • Shell 1%
  • HTML 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
marti 2aa1bd6c76
All checks were successful
ci / check (push) Successful in 40s
release / publish (release) Successful in 47s
fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does
The nix runner image has no /lib64 loader, so Biome's prebuilt binary failed with spawnSync ENOENT. scripts/ci.sh now repoints such executables at the devShell's glibc with patchelf (ELF_INTERPRETER, ELF_RPATH from flake.nix) after npm ci, and both workflows run that one script. Also put the native e2e stack under /tmp when root: nix develop's TMPDIR is 0700 and Postgres runs as nobody.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 17:50:30 +01:00
.claude chore: wire trail code graph for agents 2026-11-06 17:02:36 +01:00
.forgejo/workflows fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
.trail fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
docs fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
scripts fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
src build!: publish as @m4rti21/miniflux-mcp with a miniflux-mcp bin 2026-11-06 17:44:29 +01:00
test fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
.editorconfig build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
.env.example build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
.gitattributes build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
.gitignore build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
AGENTS.md fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
biome.json fix(lint): format only our own files and restore recommended rules 2026-11-06 17:44:29 +01:00
CLAUDE.md docs: document setup, tools, and differences from the Go server 2026-11-06 17:02:36 +01:00
flake.lock build(nix): add devShell with Node.js 24 and Docker Compose 2026-11-06 17:02:36 +01:00
flake.nix fix(ci): patch npm's prebuilt binaries for the nix runner, as mcphub does 2026-11-06 17:50:30 +01:00
LICENSE build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
opencode.json chore: wire trail code graph for agents 2026-11-06 17:02:36 +01:00
package-lock.json build!: publish as @m4rti21/miniflux-mcp with a miniflux-mcp bin 2026-11-06 17:44:29 +01:00
package.json build!: publish as @m4rti21/miniflux-mcp with a miniflux-mcp bin 2026-11-06 17:44:29 +01:00
README.md ci: publish to npm when a release is published from main 2026-11-06 17:44:29 +01:00
tsconfig.build.json build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
tsconfig.json build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00
vitest.config.ts build: scaffold TypeScript package runnable with npx 2026-11-06 17:02:27 +01:00

@m4rti21/miniflux-mcp

npm

A Model Context Protocol server for the Miniflux RSS reader. It runs over stdio, starts with npx, and covers the whole Miniflux REST API: 52 tools, 5 resources and 3 prompts.

It is a TypeScript port of tssujt/miniflux-mcp (Go). It keeps every upstream tool name and argument, fixes several upstream bugs, and adds the API endpoints upstream leaves out. The upstream comparison lists every change.

Quick start

You need Node.js 20 or newer and a Miniflux API key (Miniflux > Settings > API Keys).

MINIFLUX_URL=https://miniflux.example.com MINIFLUX_API_KEY=xxxx \
  npx -y @m4rti21/miniflux-mcp

npx downloads the package from npm, caches it, and runs the server on stdin/stdout. Pin a version with @m4rti21/miniflux-mcp@1.0.0, or install it globally with npm install -g @m4rti21/miniflux-mcp and run miniflux-mcp.

Check that it starts:

npx -y @m4rti21/miniflux-mcp --help

To run an unreleased commit, point npx at the repository instead. It builds the package on install: npx -y git+https://git.cumsek.com/marti/miniflux-mcp.git.

Claude Code

claude mcp add miniflux \
  -e MINIFLUX_URL=https://miniflux.example.com \
  -e MINIFLUX_API_KEY=xxxx \
  -- npx -y @m4rti21/miniflux-mcp

Or commit a project-level .mcp.json. Claude Code expands ${VAR} from your shell, so the key stays out of the file:

{
  "mcpServers": {
    "miniflux": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@m4rti21/miniflux-mcp"],
      "env": {
        "MINIFLUX_URL": "${MINIFLUX_URL}",
        "MINIFLUX_API_KEY": "${MINIFLUX_API_KEY}"
      }
    }
  }
}

Claude Desktop, Cursor, Windsurf, Cline and others

Every stdio MCP client takes the same block (claude_desktop_config.json, ~/.cursor/mcp.json, and so on):

{
  "mcpServers": {
    "miniflux": {
      "command": "npx",
      "args": ["-y", "@m4rti21/miniflux-mcp"],
      "env": {
        "MINIFLUX_URL": "https://miniflux.example.com",
        "MINIFLUX_API_KEY": "xxxx"
      }
    }
  }
}

From a local checkout

npm install        # also builds dist/
node dist/index.js # or: npm link && miniflux-mcp

Configuration

All configuration comes from environment variables. The server checks them at startup and exits with a clear message if one is invalid. .env.example lists them all.

Variable Default Description
MINIFLUX_URL required Miniflux base URL. A trailing / or /v1 is fine. Sub-paths such as https://example.com/miniflux work.
MINIFLUX_API_KEY API key. Recommended.
MINIFLUX_USERNAME / MINIFLUX_PASSWORD HTTP basic auth, used when no API key is set.
MINIFLUX_TIMEOUT 30 Per-request timeout in seconds.
MINIFLUX_READ_ONLY false Register only tools that never change data. Good for agents you do not fully trust.
MINIFLUX_TOOLSETS all Comma-separated subset of feeds, entries, categories, users, api_keys, system, media. Fewer tools means a smaller prompt.

If Miniflux is unreachable or the key is wrong at startup, the server logs a warning on stderr and keeps running. Every tool call then returns an error that says what to fix, so the client does not just show a dead server.

For a Miniflux server with a self-signed certificate, set Node's NODE_EXTRA_CA_CERTS=/path/to/ca.pem in the same env block.

Tools

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). Clients use them to auto-approve safe calls and to confirm before destructive ones. Tools marked new do not exist in the Go server.

Feeds

Tool Access Description
get_feeds read List feeds (ID, title, URLs, disabled, error count, category). with_counters adds unread/read counts, full returns complete objects.
get_feed read Full details of one feed, including configuration and last parsing error.
create_feed write Subscribe to a feed, with every Miniflux creation option. Returns the created feed.
update_feed write Change any feed setting; only the fields you pass are modified.
delete_feed destructive Unsubscribe and delete all of the feed's entries.
refresh_feed write Fetch a feed now; force bypasses HTTP caching.
refresh_all_feeds write Queue a refresh of every feed.
get_feed_entries read Entries of one feed, with every entry filter.
get_feed_entry read One entry of a feed.
get_feed_icon read The feed's favicon, returned as image content.
mark_feed_as_read write Mark every entry of a feed as read.
import_feed_entry write new Add an article to a feed by hand (de-duplicated by external_id or URL).

Entries

Tool Access Description
get_entries read Entries across all feeds: status, starred, full-text search, tags, date and ID ranges, sorting, pagination.
get_entry_ids read new Only the IDs matching a status/starred filter. Cheap counting and bulk work.
get_entry read One entry with content, enclosures and full feed.
update_entry_status write Mark one entry (entry_id) or a batch (entry_ids) as read, unread or removed.
set_entries_starred write new Star or unstar one or many entries explicitly.
toggle_starred write Flip the star of an entry and return the new state.
update_entry destructive new Edit the stored title and/or content.
save_entry write Send an entry to the configured integrations (Wallabag, Readwise, Pocket, ...).
fetch_original_content read Scrape the full article from the website; update_content stores it.
mark_all_as_read write Mark everything as read; user_id defaults to the current user.
flush_history destructive Remove all read, non-starred entries.

Every entry-returning tool also takes content_format and max_content_length.

  • content_format: "html" (default) returns content exactly as Miniflux stores it.
  • "text" converts it to readable plain text, which costs far fewer tokens.
  • "none" drops the content, for scanning headlines.
  • max_content_length truncates content and marks the entry content_truncated.

Entry lists return { total, count, entries }. Each entry carries a compact feed (id, title, feed_url, site_url, disabled, category) instead of the full feed object.

Categories

Tool Access Description
get_categories read List categories; with_counts adds feed_count and total_unread.
create_category write Create a category, optionally hidden from the global list.
update_category write Rename and/or set hide_globally.
delete_category destructive Delete a category with its feeds and entries.
get_category_feeds read Feeds in a category (summaries, or full).
get_category_entries read Entries in a category, with every entry filter.
get_category_entry read One entry of a category.
mark_category_as_read write Mark every entry in a category as read.
refresh_category write Refresh every feed in a category.

Users

Tool Access Description
get_me read The authenticated user and their settings.
get_users read All users (admin).
get_user_by_id read A user by ID (admin).
get_user_by_username read A user by username (admin).
create_user write Create a user (admin).
update_user write new Change credentials or any preference: theme, language, timezone, sorting, reading speed, filters, custom CSS/JS, and more. Defaults to the current user.
delete_user destructive Delete a user (admin).

System, API keys and media

Tool Access Description
get_version read Miniflux version and build info.
healthcheck read Server and database health.
fetch_counters read Read/unread counts per feed plus total_unread.
get_integrations_status read new Whether any integration is enabled (needed by save_entry).
discover read Find the feeds a website offers, with auth, cookie and proxy options.
export read All subscriptions as OPML.
import_opml write new Import subscriptions from an OPML document.
get_api_keys read List API keys. Tokens are never shown.
create_api_key write Create an API key; the token appears only in this response.
delete_api_key destructive Revoke an API key.
get_icon read An icon by icon ID, as image content.
get_enclosure read An enclosure (podcast audio, video, ...) with its playback position.
update_enclosure write new Save the playback position of an enclosure.

Resources

URI Content
miniflux://feeds All feeds with unread counts (JSON)
miniflux://categories All categories with counts (JSON)
miniflux://opml OPML export
miniflux://feeds/{feed_id} One feed (JSON)
miniflux://entries/{entry_id} One article as Markdown: title, metadata, plain-text body

Prompts

Prompt What it does
daily_digest Summarizes unread articles from the last hours (default 24), grouped by topic, optionally for one category.
triage_unread Sorts unread headlines into "read now", "star for later" and "mark as read", then applies the plan when you confirm.
subscribe Discovers the feed of a website url, then subscribes to it, optionally into a category.

Differences from the Go server

Bugs fixed:

  • create_feed sent category_id: 1 when none was given. That category belongs only to the first user, so the call failed for everyone else. This server lets Miniflux pick the user's own first category. It also returns the created feed; upstream returned a bare number.
  • get_user_by_username did not URL-escape the username.
  • Upstream reduced all 4xx errors to generic strings such as miniflux: resource not found. This server returns the HTTP status, the endpoint, and Miniflux's own error_message, plus a hint for 401 and 403.
  • IDs are validated as positive integers by JSON Schema. Upstream accepted any number and truncated it.

Added:

  • 8 more endpoints (marked new above).
  • entry_ids batches on update_entry_status.
  • A tags filter, force refresh, and category with_counts.
  • All of Miniflux's feed creation and discovery options, and the missing feed fields (description, ignore_entry_updates, no_media_player).
  • content_format and max_content_length on every entry tool.
  • Icons returned as MCP image content.
  • MCP tool annotations, resources, prompts, and server instructions that teach the model the efficient workflow.
  • MINIFLUX_READ_ONLY, MINIFLUX_TOOLSETS and MINIFLUX_TIMEOUT.
  • The server stays up when Miniflux is unreachable at startup.
  • mark_all_as_read defaults to the current user.
  • toggle_starred reports the new state.
  • get_api_keys never leaks tokens.

Removed on purpose: the Streamable HTTP transport. This is a stdio-only server.

Development

Three ways to get a toolchain:

  • Plain Node.js: Node 20+ and npm. The e2e tests also need Docker, or miniflux and Postgres on the PATH.
  • Nix: run nix develop. It provides Node.js 24, Docker Compose, Miniflux and Postgres.
  • Docker only: docker run --rm -it -v "$PWD:/app" -w /app node:24 npm ci, then run the commands below the same way.
Command What it does
npm install Install dependencies and build dist/
npm run build / npm run dev Compile once / in watch mode
npm test Unit tests (fast, no network)
npm run test:e2e Builds, starts Postgres + Miniflux + a fixture feed site, drives the real server over stdio through every tool, then tears it down
npm run typecheck / npm run lint / npm run format Type check, lint, format

The e2e stack runs in one of two ways. E2E_MINIFLUX=docker uses Docker Compose. E2E_MINIFLUX=native uses the initdb, postgres and miniflux binaries from the PATH, which is how CI runs it. Without the variable, Docker is used when a daemon is reachable.

With Docker, E2E_KEEP_STACK=1 npm run test:e2e leaves the stack running, with Miniflux on http://127.0.0.1:18080 (login admin / test123456). Set MINIFLUX_E2E_PORT to use another port. The architecture and test layout are in docs/development.md.

Releasing

Bump version in package.json on main, then publish a Forgejo release tagged v<version> from main. The release workflow runs every check, then publishes @m4rti21/miniflux-mcp to npm and attaches the tarball to the release. The one-time setup is in docs/releasing.md.

Note: Miniflux 2.3 and later refuses to fetch feeds on private networks. If your feeds live on your LAN, set FETCHER_ALLOW_PRIVATE_NETWORKS=1 on Miniflux. This setting belongs to Miniflux, not to this server.

License

MIT. See LICENSE. Based on the MIT-licensed tssujt/miniflux-mcp.