- TypeScript 87.7%
- JavaScript 9.5%
- Nix 1%
- Shell 1%
- HTML 0.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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> |
||
| .claude | ||
| .forgejo/workflows | ||
| .trail | ||
| docs | ||
| scripts | ||
| src | ||
| test | ||
| .editorconfig | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| opencode.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| vitest.config.ts | ||
@m4rti21/miniflux-mcp
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_lengthtruncates content and marks the entrycontent_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_feedsentcategory_id: 1when 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_usernamedid 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 ownerror_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_idsbatches onupdate_entry_status.- A
tagsfilter,forcerefresh, and categorywith_counts. - All of Miniflux's feed creation and discovery options, and the missing feed
fields (
description,ignore_entry_updates,no_media_player). content_formatandmax_content_lengthon 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_TOOLSETSandMINIFLUX_TIMEOUT.- The server stays up when Miniflux is unreachable at startup.
mark_all_as_readdefaults to the current user.toggle_starredreports the new state.get_api_keysnever 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
minifluxand 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.