freshrss-mcp

Model Context Protocol サーバーで、 セルフホスト型 RSS/Atom フィードアグリゲーター FreshRSS に対応するものです。

FreshRSS が /api/greader.php で公開している Google Reader 互換 API を利用し、その API の癖を、アシスタントが実際に使いやすいツール引数（数値のフィード ID、カテゴリー名やラベル名、ISO 日付、10 進数の記事 ID など。user/-/state/com.google/… ストリーム識別子や 16 進数のアイテムタグは使いません）で隠蔽します。

📖 完全なドキュメント: freshrss-mcp.ni-c.de

必要条件

• Node.js 22 以降

• FreshRSS インスタンス（バージョン 1.29 で開発）で、以下が有効であること:

  • API が有効: 設定 → 認証 → 「API アクセスを許可」

  • ユーザーに API パスワード が設定されている: 設定 → プロフィール → API 管理。 これは Web ログインパスワードとは別のパスワードです。

Related MCP server: Conduit

設定

サーバーは認証情報なしでも起動するため、ツールは一覧表示可能です。ただし、すべての呼び出しはこのセットアップ手順とともに失敗します。

Claude Code

claude mcp add freshrss -- npx -y @ni-c/freshrss-mcp

Claude Desktop

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": {
        "FRESHRSS_URL": "https://rss.example.com",
        "FRESHRSS_USER": "alice",
        "FRESHRSS_API_PASSWORD": "…"
      }
    }
  }
}

Codex

[mcp_servers.freshrss]
command = "npx"
args = ["-y", "@ni-c/freshrss-mcp"]
env = { FRESHRSS_URL = "https://rss.example.com", FRESHRSS_USER = "alice", FRESHRSS_API_PASSWORD = "…" }

ツール

読み取り

書き込み

FRESHRSS_READ_ONLY=true の場合は登録されません。

検索なし

FreshRSS は API 経由で全文検索を提供していません。Google Reader エンドポイントはストリーム、既読状態、日付でのみフィルタリングします。そのため list_articles にはクエリパラメータがありません。feed_id/category と since/until で結果を絞り込み、返された記事を自分でフィルタリングしてください。

安全性

• 記事テキストは信頼できない入力です。 このサーバーが FreshRSS から返すものはすべてインターネット上の第三者が作成したものであるため、記事テキスト、タイトル、フィード名を含む応答は明示的にデータとしてマークされ、決して指示としては扱われません。

• 破壊的なツールは 2 段階です。 最初の呼び出しは、対象を正確に指定した使い捨ての確認トークンを返します。2 回目の呼び出しでそのトークンを提示する必要があります。単純なブール値では、最初の呼び出しで設定されたり、フィード内の隠しテキストで誘導されたりする可能性があります。確認メッセージでは、API から取得したタイトルや名前を意図的に引用しません。

• 応答予算。 FreshRSS は記事ごとに最大 500,000 文字の HTML を返します。記事テキストはプレーンテキストに変換され、記事ごと、および応答ごとの予算に対して上限が設定され、一覧表示ではオプトインとなります。

• 認証情報 は一度だけ読み取られ、その後 process.env から削除され、ディスクに書き込まれることはありません。リクエストはリダイレクトを決して追跡しません（リダイレクト先に認証ヘッダーが再送信されるのを防ぐため）。また、TLS 検証の緩和はプロセス全体ではなく、この接続のみに適用されます。

• フィード URL は秘匿化されます。 FreshRSS は HTTP 認証付きフィードを https://user:password@host/feed として保存します。ツールの結果や OPML エクスポートにフィード URL が出力される前に、ユーザー情報部分は削除されるため、list_feeds で有料フィードやプライベートフィードのパスワードがトランスクリプトに出力されることはありません。

• subscribe_feed は内部ターゲットを拒否します。 FreshRSS はサーバー側で URL を取得するため、このツールは記事内のテキストから到達可能な SSRF プリミティブになります。ループバックアドレスとリンクローカルアドレス（クラウドメタデータエンドポイントを含む）は拒否されます。プライベート LAN アドレスは許可されます。これは、セルフホスト環境では自社ネットワーク上のフィードを正当に購読するためです。

• import_opml は <!DOCTYPE> を拒否します。 このプロセスでは XML は解析されませんが、文書は FreshRSS に渡されます。文書型宣言はエンティティ展開攻撃や外部エンティティ攻撃の媒体となります。OPML に文書型は不要です。

• FRESHRSS_READ_ONLY=true に設定すると、書き込みツールは呼び出し時に拒否されるのではなく、そもそも登録されません。

確認トークンで保護されるツール: mark_all_as_read、unsubscribe_feed、delete_category_or_label、import_opml。mark_articles は意図的に保護されていません — 呼び出し元は最大 100 件の記事をそれぞれ明示的に指定し、すべてのフィールドを元に戻すことができます — ただし、破壊的として宣言されているため、クライアントが確認を求める場合があります。

コンテナ

docker run --rm -i \
  -e FRESHRSS_URL=https://rss.example.com \
  -e FRESHRSS_USER=alice \
  -e FRESHRSS_API_PASSWORD=... \
  ghcr.io/ni-c/freshrss-mcp:latest

イメージは linux/amd64 と linux/arm64 向けに公開されており、SBOM とビルド来歴が付属しています。非特権 node ユーザーとして実行され、npm は含まれていません。そのため、中には Node、ランタイム依存関係、および dist/ のみが含まれています。

開発

npm install
npm run lint && npm run build && npm test
npm run test:coverage

開発用の使い捨て FreshRSS については CONTRIBUTING.md を参照してください。完全なドキュメントは freshrss-mcp.ni-c.de にあります。

リリース

1. CHANGELOG.md の [Unreleased] エントリを新しいバージョンに移動し、package.json の version を更新します。

2. npm run lint && npm run build && npm run test:coverage を実行します。

3. コミットし、タグ付け: git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z。

タグによって release.yml がトリガーされ、タグが package.json と一致することを確認し、Trusted Publishing を使用して来歴付きで npm に公開し（トークン不要）、CHANGELOG セクションから GitHub リリースを作成し、MCP Registry にエントリを公開します。レジストリステップのみが失敗した場合は、main で修正し、mcp-registry.yml を手動で再実行してください。タグ付きジョブを再実行しないでください。古いツリーをチェックアウトすることになります。

ライセンス

MIT