使用说明

FreshRSS MCP服务器

一个MCP（模型上下文协议）服务器，连接到自托管的FreshRSS实例，使AI应用程序能够获取和管理RSS订阅文章。

特性

获取未读文章：从您的RSS订阅中获取所有未读文章
文章内容：访问包含标题、摘要、链接和发布日期的完整文章内容
完整文章报废：从原始URL中提取完整的文章文本（仅用于摘要提要）
标记为已读：处理后将文章标记为已读
订阅管理：查看所有有未读计数的订阅

安装

先决条件

Python 3.14+
紫外线包管理器
自托管新鲜RSS 已启用API的实例

设置

克隆存储库：

git clone https://github.com/yourusername/freshrss-mcp-server.git
cd freshrss-mcp-server

安装依赖项：

uv sync

# Install Playwright browser (required for dynamic fetch)
uv run playwright install chromium

创建 .env 使用您的FreshRSS凭据创建文件：

cp .env.example .env
# Edit .env with your credentials

配置

创建一个 .env 包含以下变量的文件：

# Required: FreshRSS API
FRESHRSS_API_URL=https://your-freshrss-instance/api/greader.php
FRESHRSS_USERNAME=your_username
FRESHRSS_API_PASSWORD=your_api_password

# Optional: Request settings
REQUEST_TIMEOUT=30
DEFAULT_ARTICLE_LIMIT=100

# Optional: MCP Server (defaults shown)
MCP_TRANSPORT=sse           # "stdio", "sse", or "streamable-http"
MCP_HOST=::                 # HTTP server host (:: = all interfaces)
MCP_PORT=8080               # HTTP server port

# Optional: Dynamic content fetching (Playwright)
ENABLE_DYNAMIC_FETCH=true   # Enable browser rendering for JS-heavy sites
BROWSER_TIMEOUT=30          # Page load timeout in seconds

# Optional: API Authentication (for remote deployments)
API_KEY=your-secret-key     # If set, clients must use Authorization: Bearer <key>

# Optional: Logging
LOG_LEVEL=INFO              # DEBUG, INFO, WARNING, ERROR, CRITICAL

FreshRSS API设置

在FreshRSS中，转到“设置”>“个人资料”
启用“允许API访问”
设置API密码（与您的登录密码不同）
在您的 .env 文件

用法

运输方式

服务器支持三种传输模式：

模式	用例	端点
上海证券交易所	远程部署（传统客户端）	`/sse`
可流式传输的HTTP	远程部署（推荐）	`/mcp`
工作室	本地（克劳德桌面直接）	不适用

运行服务器

SSE模式 （默认）：

uv run freshrss-mcp

流式HTTP模式 （建议用于新部署）：

uv run freshrss-mcp --transport streamable-http

STDIO模式 （适用于克劳德桌面本地）：

uv run freshrss-mcp --transport stdio

CLI选项:

--transport {stdio,sse,streamable-http}  Transport mode (default: sse)
--host HOST              HTTP server host (default: ::)
--port PORT              HTTP server port (default: 8080)
--version                Show version

健康检查

对于SSE和Streamable HTTP模式，可以使用健康检查端点：

curl http://localhost:8080/health
# {"status": "healthy", "version": "0.1.0", "transport": "streamable-http"}

API身份验证

当 API_KEY 设置后，所有MCP端点都需要身份验证：

curl -H "Authorization: Bearer your-secret-key" https://your-server/mcp

安全注意事项：

FreshRSS凭据是服务器端的秘密——客户端永远看不到它们
客户只需要 API_KEY 访问MCP服务器
始终使用HTTPS进行公共部署
这 /health 端点不需要身份验证

Claude桌面配置

远程服务器（推荐）

要连接到已部署的服务器（Railway、Docker等），请使用 mcp-remote:

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-server.example.com/mcp",
        "--header", "Authorization: Bearer ${YOUR_API_KEY}"
      ]
    }
  }
}

本地服务器（STDIO）

要在本地运行服务器：

{
  "mcpServers": {
    "freshrss": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/freshrss-mcp-server", "freshrss-mcp", "--transport", "stdio"],
      "env": {
        "FRESHRSS_API_URL": "https://your-freshrss-instance/api/greader.php",
        "FRESHRSS_USERNAME": "your_username",
        "FRESHRSS_API_PASSWORD": "your_api_password"
      }
    }
  }
}

部署

Docker部署

使用Docker Compose（推荐）：

# Create .env file with your credentials
cat > .env << EOF
FRESHRSS_API_URL=https://your-freshrss/api/greader.php
FRESHRSS_USERNAME=your_username
FRESHRSS_API_PASSWORD=your_password
API_KEY=your-secret-key
EOF

# Start the service
docker compose up -d

# Check logs
docker compose logs -f

或者手动构建并运行：

docker build -t freshrss-mcp .
docker run -p 8080:8080 \
  -e FRESHRSS_API_URL=https://your-freshrss/api/greader.php \
  -e FRESHRSS_USERNAME=your_username \
  -e FRESHRSS_API_PASSWORD=your_password \
  -e API_KEY=your-secret-key \
  freshrss-mcp

Docker镜像包括：

健康检查配置
Playwright浏览器已预装
流式HTTP作为默认传输

铁路部署

如果您已经在那里部署了FreshRSS，那么Railway是理想的选择——同一项目中的服务可以通过专用网络进行通信。

步骤1：部署到铁路

# In your freshrss-mcp-server directory
railway link  # Link to your existing project
railway up    # Deploy

步骤2：配置环境变量

在铁路仪表板中，添加以下变量：

# Use internal networking if FreshRSS is in same project (faster, no egress cost)
FRESHRSS_API_URL=http://freshrss.railway.internal:80/api/greader.php

# Your FreshRSS credentials
FRESHRSS_USERNAME=your_username
FRESHRSS_API_PASSWORD=your_api_password

# Recommended settings
MCP_TRANSPORT=streamable-http
ENABLE_DYNAMIC_FETCH=true
API_KEY=your-secret-key

步骤3：生成公共域

在铁路仪表板中，转到设置>网络>生成域。

裸机/VM部署

使用提供的安装脚本：

sudo ./deploy/install.sh
sudo nano /opt/freshrss-mcp-server/.env
sudo systemctl enable freshrss-mcp
sudo systemctl start freshrss-mcp

可用工具

`get_unread_articles`

从FreshRSS获取未读文章。

参数：

limit （可选，默认值：100）：要返回的最大文章数
feed_id （可选）：按特定提要ID筛选

退货： 带有id、标题、摘要、链接、已发布、feed_title的文章列表

`get_article_content`

获取特定文章的完整内容。

参数：

article_id：要获取的文章ID

退货： 内容完整的文章

`mark_as_read`

将文章标记为已读。

参数：

article_ids：要标记为已读的文章ID列表

退货： 具有成功状态的操作结果

`get_subscriptions`

获取所有包含未读计数的RSS订阅源。

退货： 包含id、标题、url、未读计数和类别的订阅列表

`fetch_full_article`

从原始URL获取完整的文章内容（仅用于摘要提要）。

参数：

url：要获取的原始文章URL
force_dynamic （可选，默认值：false）：对JS渲染的页面使用Playwright浏览器

退货： 提取的文章内容，包括标题、文本和方法（“静态”或“动态”）

工作流示例

AI呼叫 get_unread_articles 获取未读文章列表
AI分析标题和摘要以确定重要性
对于不完整的摘要，AI调用 fetch_full_article 获取完整内容
AI为所有文章生成摘要报告
用户评论后，AI呼叫 mark_as_read 将文章标记为已读

发展

MCP检查员（本地调试）

使用MCP Inspector web UI交互式测试和调试服务器：

npx @modelcontextprotocol/inspector uv run python -m freshrss_mcp_server.server

运行测试

# Quick API test
uv run python -c "
import asyncio
from freshrss_mcp_server.api.client import FreshRSSClient
from freshrss_mcp_server.config import get_settings

async def test():
    settings = get_settings()
    async with FreshRSSClient(
        settings.freshrss_api_url,
        settings.freshrss_username,
        settings.freshrss_api_password,
    ) as client:
        subs = await client.get_subscriptions()
        print(f'Found {len(subs)} subscriptions')

asyncio.run(test())
"

过梁和类型检查

# Format code
ruff format .

# Check for issues
ruff check .

# Type check
uv run ty check .

技术栈

Python 3.14
紫外线 -包管理器
拉夫 -过梁/格式化工具
吨年 -类型检查器
MCP-SDK -模型上下文协议
httpx -异步HTTP客户端
派丹蒂克 -数据验证
交通 -静态文章内容提取
剧作家 -动态内容渲染（适用于JS密集型网站）

许可证

MIT许可证-请参阅许可证了解详情。

使用说明

FreshRSS MCP服务器

特性

安装

先决条件

设置

配置

FreshRSS API设置

用法

运输方式

运行服务器

健康检查

API身份验证

Claude桌面配置

远程服务器（推荐）

本地服务器（STDIO）

部署

Docker部署

铁路部署

裸机/VM部署

可用工具

get_unread_articles

get_article_content

mark_as_read

get_subscriptions

fetch_full_article

工作流示例

发展

MCP检查员（本地调试）

运行测试

过梁和类型检查

技术栈

许可证

相关 MCP

RSS智能管理工具

RSS智能管理服务器

RSS管理分析服务器

微信公众号文章爬取服务

FreshRSS管理协议服务器

RSS订阅管理服务

`get_unread_articles`

`get_article_content`

`mark_as_read`

`get_subscriptions`

`fetch_full_article`