Freshrss MCP Server (Darknight)

FreshRSS MCP服务器

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

特性

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

安装

先决条件

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

设置

1. 克隆存储库：

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

1. 安装依赖项：

uv sync

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

1. 创建 .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 

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

FreshRSS API设置

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

用法

运输方式

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

运行服务器

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 网络>生成域。

### 裸机/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浏览器

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

## 工作流示例

1. AI呼叫 `get_unread_articles` 获取未读文章列表
1. AI分析标题和摘要以确定重要性
1. 对于不完整的摘要，AI调用 `fetch_full_article` 获取完整内容
1. AI为所有文章生成摘要报告
1. 用户评论后，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许可证-请参阅 [许可证](LICENSE) 了解详情。