freshrss-mcp

자체 호스팅 RSS 및 Atom 피드 수집기인 FreshRSS를 위한 Model Context Protocol 서버입니다.

이 서버는 FreshRSS가 /api/greader.php에서 제공하는 Google Reader 호환 API를 사용하며, 어시스턴트가 실제로 사용할 수 있는 도구 인수 뒤에 해당 API의 특이점을 숨깁니다: user/-/state/com.google/… 스트림 식별자와 16진수 항목 태그 대신 숫자 피드 ID, 카테고리 및 레이블 이름, ISO 날짜 및 10진수 기사 ID를 사용합니다.

📖 전체 문서: freshrss-mcp.ni-c.de

요구 사항

• Node.js 22 이상

• 다음 조건을 갖춘 FreshRSS 인스턴스 (1.29 기준으로 개발됨)

  • API 활성화: 설정 → 인증 → "API 접근 허용"

  • 사용자에 대한 API 비밀번호 설정: 설정 → 프로필 → API 관리. 이는 웹 로그인 비밀번호와 별개입니다.

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에서 반환하는 모든 것은 인터넷의 제3자가 작성한 것이므로, 기사 텍스트, 제목 또는 피드 이름을 포함하는 응답은 명시적으로 데이터로 표시되며 지시사항으로 표시되지 않습니다.

• 파괴적인 도구는 두 단계로 이루어집니다. 첫 번째 호출은 정확한 대상에 바인딩된 일회용 확인 토큰을 반환하며, 두 번째 호출은 이를 전달해야 합니다. 일반 부울 값은 첫 번째 호출에서 설정되거나 피드에 숨겨진 텍스트에 의해 설정되도록 유도될 수 있습니다. 확인 메시지는 의도적으로 API에서 오는 제목이나 이름을 인용하지 않습니다.

• 응답 예산. FreshRSS는 기사당 최대 500,000자의 HTML을 반환합니다. 기사 텍스트는 일반 텍스트로 변환되고, 기사당 및 응답당 예산에 대해 제한되며, 목록에서는 선택 사항입니다.

• 자격 증명은 한 번 읽힌 후 process.env에서 제거되며 디스크에 기록되지 않습니다. 요청은 리디렉션을 따르지 않으며 (리디렉션 시 인증 헤더가 다른 호스트로 다시 전송됨), 완화된 TLS 검증은 전체 프로세스가 아닌 이 연결에만 적용됩니다.

• 피드 URL은 수정됩니다. FreshRSS는 HTTP 인증 피드를 https://user:password@host/feed로 저장합니다. 피드 URL이 도구 결과나 OPML 내보내기에 도달하기 전에 사용자 정보 부분이 제거되므로 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