FreshRSS

freshrss-mcp

FreshRSS 用の Model Context Protocol（MCP）サーバーです。セルフホスト型の RSS・Atom フィードアグリゲーターです。

Claude Code、Claude Desktop、Codex などの MCP クライアントがフィードを利用できます。未読記事の確認、記事の閲覧、既読設定、購読やカテゴリーの管理が可能です。

ツールは 16 個まで登録できますが、必ずしもすべて登録する必要はありません。FRESHRSS_ALLOW_TOOLS=essential を設定すると、厳選された 7 個だけを登録します。16 個より 7 個の方が、モデルは適切なツールをはるかに確実に選択できます。詳しくは読み込むツールの選び方をご覧ください。

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

特長

16 個のツール、ストリーム ID は不要。 Google Reader API はストリーム識別子と 16 進数の記事タグを使います。このツールでは数値のフィード ID、カテゴリー名とラベル名、ISO 日付、10 進数の記事 ID を使用し、生の HTML ではなくプレーンテキストを返します。

信頼できないフィードを想定した設計。 すべての記事はインターネット上の見知らぬ人が書いたものです。そのため、応答はデータとしてマークされ、フィード URL から認証情報が除去され、記事のテキスト量は記事ごとおよび応答ごとに制限されます。取り消し不能な 5 個のツールでは、MCP elicitation を通じて事前にユーザーへ確認します。

要件

• Node.js 22 以降
• FreshRSS インスタンス（1.29 を対象に開発）
  • API が有効になっていること：設定 → 認証 →「API アクセスを許可」
  • ユーザーに API パスワードが設定されていること：設定 → プロフィール → API 管理。 これは Web ログイン用のパスワードとは別のものです。

設定

変数	必須	説明
FRESHRSS_URL	はい	インスタンスのルート URL です。例：https://rss.example.com。API パス /api/greader.php は自動的に追加されます。
FRESHRSS_USER	はい	FreshRSS のユーザー名です。
FRESHRSS_API_PASSWORD	はい	プロフィールページにある API パスワードです。Web ログインのパスワードではありません。
FRESHRSS_READ_ONLY	いいえ	1、true、または yes を指定すると、読み取りツールのみを登録します。
FRESHRSS_INSECURE_TLS	いいえ	true を指定すると、この接続に限り自己署名証明書を許可します。
FRESHRSS_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* の接頭辞、または厳選されたプリセットを指定する essential
FRESHRSS_DENY_TOOLS	いいえ	同じ構文です。FRESHRSS_ALLOW_TOOLS で残ったものから除外します。
ELICITATION	いいえ	false を指定すると、承認ダイアログを 2 回呼び出すトークンに置き換えます。接頭辞は付きません。

認証情報がなくてもサーバーは起動するため、ツールの一覧表示は可能です。ただし、その後のすべての呼び出しは、以下の設定手順とともに失敗します。

読み込むツールを選ぶ

FRESHRSS_ALLOW_TOOLS と FRESHRSS_DENY_TOOLS には、カンマ区切りのツール名を指定します。末尾の * はファミリー全体に一致します。essential は、次の 7 つをまとめた厳選プリセットです：list_feeds、list_categories、get_unread_counts、list_articles、get_articles、mark_articles、mark_all_as_read。

FRESHRSS_ALLOW_TOOLS=essential
FRESHRSS_ALLOW_TOOLS=list_feeds,list_articles,mark_articles
FRESHRSS_DENY_TOOLS=delete_*

どのツールにも一致しない項目があると、その項目名を示して起動を中断します。これにより、タイプミスでツールが気付かれないまま非表示になることはありません。存在しないツールを環境変数と結び付けて調査する人はいないためです。フィルターされたツールは登録されないため、tools/list にも現れず、tools/call でも未知のツールとして扱われます。これは、FRESHRSS_READ_ONLY の設定で書き込みツールが使えなくなるのと同じです。

これらのサーバーを複数同時に実行する場合は、mcp-hub がもう一つの選択肢です。/hub エンドポイントを使うと、各サーバーのツールが 6 つのメタツールに置き換わります。

インストール

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 = "…" }

Docker

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/ のみです。

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、Web 版 Claude、Cursor、LibreChat）は、mcp-hub 経由で freshrss-mcp に接続します。1 つのコンテナーで複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、単一のパスワードを使った OAuth 2.1 ログインと、OAuth を利用できないクライアント向けの長期トークンを備えています。/hub エンドポイントでは、すべてのサーバーが 6 つのメタツールの背後に置かれるため、モデルのコンテキストに N×ツールのスキーマを含めることなく、1 つのコネクターですべてのサーバーにアクセスできます。また、両方のプロトコルリビジョンに対応しているため、このサーバーが尋ねる質問は、経由先にいる人まで届きます。

/config/mcp.json は Claude Code 形式を使うため、エントリーにはすでにお持ちのものをそのまま使えます。

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": { "FRESHRSS_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

ここでの allowTools と denyTools は、サーバーごとに設定するハブ独自のフィルターであり、env 内の *_ALLOW_TOOLS と同じものではありません。その違いと、そこから生じる間違いについては、クライアントガイドをご覧ください。

ツール

読み取り

ツール	説明
get_user_info	認証済みアカウントです。認証情報を手早く確認できます。
list_feeds	すべての購読フィードと、そのカテゴリおよび未読件数です。
list_categories	カテゴリ（フィードのフォルダー）とユーザーラベル（記事のタグ）です。
get_unread_counts	フィード／カテゴリごとの未読件数と合計を、並べ替えて表示します。
list_articles	フィード、カテゴリ、ラベル、または組み込みストリームの記事を、抜粋または長さを制限した全文とともに取得します。
get_articles	IDを指定して、特定の記事の全文を取得します。
list_article_ids	IDのみを取得します。mark_articles に渡すIDを手軽に集められます。
export_opml	すべての購読をOPMLドキュメントとして出力します。

書き込み

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

ツール	説明	確認
mark_articles	特定の記事の既読状態、スター、ラベルを設定します。	—
mark_all_as_read	フィード、カテゴリ、ラベル、またはストリーム全体を既読にします。	はい
subscribe_feed	フィードまたはウェブサイトのURLを購読します。	—
update_feed	フィードの名前を変更するか、別のカテゴリに移動します。	—
unsubscribe_feed	フィードと、保存されているすべての記事を削除します。	はい
rename_category_or_label	カテゴリまたはユーザーラベルの名前を変更します。	—
delete_category_or_label	カテゴリまたはユーザーラベルを削除します。	はい
import_opml	OPMLドキュメント内のすべてのフィードを購読します。	はい

構造化出力

すべてのツールは outputSchema を宣言し、テキストブロックに加えて structuredContent で応答するため、クライアントは文章を解析せずに結果を利用できます。

{
  "untrusted": true,
  "source": "freshrss",
  "articles": [{ "id": "1234", "title": "…", "read": false, "starred": false }],
  "continuation": "1699999999",
  "notes": ["…"],
}

フィードの内容を報告するすべてのツールは、フィールドとして untrusted: true と source: "freshrss" を含みます。このサーバーはこれまでも notes でそう伝えていました。 notes はリスト内の文章であり、クライアントは読めても確認はできませんが、このフィールドによって 確認できるようになります。8つのツールにはこのフィールドがありません。応答がすべて このサーバー独自の内容、つまり与えられたID、引数から作成された文、認証に使用するアカウントだからです。

以前は6つのツールが文（「フィード9を削除しました。」）で応答していましたが、現在はフィールドも返し、 文はテキストブロックに残ります。 export_opml はドキュメント全体ではなく {opml} を返します。ルートが文字列のスキーマは、 2025年当時のクライアント向けに {result: …} として書き換えられるため、 どちらにしても truncated の格納先が必要です。

検索なし

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

意図的に公開していない機能

全文検索はありません。 FreshRSS は Google Reader API で全文検索を提供していないためです。エンドポイントで絞り込めるのは、フィード、既読状態、日付のみです。feed_id、category、since、until で絞り込んだうえで、返された記事を自分でフィルターしてください。FreshRSS のウェブインターフェースにある検索には、対応する API エンドポイントがありません。

生の HTML はありません。 記事の本文はプレーンテキストに変換され、記事ごとおよびレスポンスごとに上限が設定されているため、1 つの記事一覧がコンテキストをほかのすべての内容で埋め尽くすことはありません。

安全性

• 記事のテキストは信頼できない入力です。 このサーバーが FreshRSS から返す内容はすべてインターネット上の第三者が作成したものです。そのため、記事のテキスト、タイトル、フィード名を含むレスポンスには、指示ではなくデータであることが明示されています。
• 人に確認を求めます。単に伝えるだけではありません。 クライアントが MCP のエリシテーションに対応している場合、取り消せない 5 つのツールは実際のダイアログを表示し、モデルが人に代わって回答できないようにします。単純なブール値なら最初の呼び出しで設定できてしまうほか、フィード内に隠されたテキストによって誘導される可能性もあります。クライアントがダイアログを表示できない場合は、対象を正確に指定した使い切りトークンに切り替え、誰かが承認したかのように装うのではなく、その旨を明示します。メッセージには、API から取得したタイトルや名前を意図的に引用しません。人に確認を求めるを参照してください。
• レスポンスの予算。 FreshRSS は記事ごとに最大 500 000 文字の HTML を返します。記事のテキストはプレーンテキストに変換され、記事ごとの上限とレスポンスごとの予算が適用されます。また、一覧ではオプトイン方式です。予算は変換後のテキストではなく、読み込んだマークアップに対して消費されるため、結果として得られるコンテキストだけでなく、変換処理の作業量も制限できます。何も残らないほどマークアップが取り除かれるケースが最も高コストであり、以前はその処理が無料でした。変換処理自体は左から右への 1 回のスキャンであり、記事の内容にかかわらず、記事の長さに対して線形です。
• 認証情報は一度だけ読み込まれ、その後 process.env から削除され、ディスクに書き込まれることはありません。リクエストはリダイレクトを一切追跡しません。リダイレクトを追跡すると、認証ヘッダーが別のホストに再送されるためです。また、TLS 検証の緩和はプロセス全体ではなく、この接続にのみ適用されます。
• フィード URL は秘匿化されます。 FreshRSS は HTTP 認証付きフィードを https://user:password@host/feed として保存します。フィード URL がツールの結果や OPML エクスポートに渡される前に userinfo 部分が取り除かれるため、list_feeds が有料または非公開のフィードのパスワードをトランスクリプトに出力することはありません。
• subscribe_feed と import_opml は内部向けの対象を拒否します。 FreshRSS はこれらの URL をサーバー側で取得するため、どちらのツールも記事内のテキストから実行可能な SSRF の手段になり得ます。ループバックアドレスとリンクローカルアドレス（クラウドのメタデータエンドポイントを含む）は、フィード URL と OPML ドキュメント内のすべての xmlUrl／htmlUrl について拒否されます。アドレスは数値として比較されるため、[::ffff:169.254.169.254] のような IPv4 マップ IPv6 リテラルも検出され、ホスト名は受け入れ前に名前解決されます。OPML ドキュメントは XML パーサーが読み取る方法で読み取られ、検査済みのドキュメントがそのまま FreshRSS に渡されます。そのため、検査された URL と実際に取得される URL は同じです。セルフホスト環境では、自身のネットワーク上のフィードを正当に購読することがあるため、プライベート 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 です。スターの付与、スターの解除、ラベル付けはすべて元に戻せますが、どの記事が未読だったかは元に戻せず、FreshRSS にもその記録は残りません。

ドキュメント

完全なガイド、ツールリファレンス、セキュリティに関する注意事項は freshrss-mcp.ni-c.de にあります（ソースは docs/ にあります）。

開発

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 と一致することを確認したうえで、provenance 付きの Trusted Publishing を使って npm に公開します（トークンは不要です）。また、CHANGELOG の該当セクションから GitHub リリースを作成し、MCP Registry にエントリーを公開します。レジストリの手順だけが失敗した場合は、main で修正してから mcp-registry.yml を手動で再実行してください。タグ付きジョブは古いツリーをチェックアウトするため、決して再実行しないでください。

コントリビュート

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。脆弱性については、公開 Issue ではなく非公開で報告してください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel