使用说明

MCP RSS

MCP RSS是一个模型上下文协议（MCP）服务器，用于智能RSS提要管理，具有高级搜索功能、使用AI嵌入的语义搜索和全面的阅读工作流程。

特性

📰 RSS源管理 -解析OPML文件并自动从RSS提要中获取文章
🔍 高级搜索 -具有日期范围、类别和状态过滤的关键字搜索
🤖 语义搜索 -使用OpenAI嵌入的人工智能驱动的自然语言搜索（可选）
📊 智能组织 -四状态工作流（未读/已读/收藏/已存档）
📅 每日摘要 -获取按类别分组的今天未读文章
🚀 高性能 -PostgreSQL与pgvector的高效向量相似性搜索
🔄 自动重复数据删除 -防止重复的文章和浪费的API调用
⚡ 代币高效 -首先浏览标题/摘录，仅在需要时获取完整内容
📑 分页支持 -通过高效分页处理大型饲料收集（500+）

安装

先决条件

Node.js（v18或更高版本）
Docker和Docker Compose（用于PostgreSQL和pgvector）
OpenAI API密钥（可选，仅用于语义搜索）

Docker Compose快速入门

克隆或安装软件包：

npm install -g mcp_rss
# OR for local development
git clone <repository-url>
cd mcp_rss
npm install

用pgvector启动PostgreSQL：
```
docker-compose up -d
```

配置环境变量：

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

构建项目：
```
npm run build
```

数据库设置

该项目使用PostgreSQL 17和pgvector扩展进行向量相似性搜索。

使用Docker Compose（推荐）：

docker-compose up -d             # Start PostgreSQL
docker-compose down              # Stop PostgreSQL
docker-compose down -v           # Stop and remove volumes (fresh start)
docker-compose logs -f postgres  # View PostgreSQL logs

PostgreSQL手动设置：

docker run -d \
  --name mcp-rss-postgres \
  -p 5433:5432 \
  -e POSTGRES_USER=mcp_user \
  -e POSTGRES_PASSWORD=123456 \
  -e POSTGRES_DB=mcp_rss \
  pgvector/pgvector:pg17

配置

环境变量

创建一个 .env 具有以下配置的文件：

变量	描述	默认值	必填
数据库配置
`DB_HOST`	PostgreSQL主机	`localhost`	没有
`DB_PORT`	PostgreSQL端口	`5433`	没有
`DB_USER` / `DB_USERNAME`	数据库用户名	`mcp_user`	没有
`DB_PASSWORD`	数据库密码	`123456`	没有
`DB_NAME` / `DB_DATABASE`	数据库名称	`mcp_rss`	没有
RSS配置
`OPML_FILE_PATH`	带有RSS源的OPML文件路径	`./feeds.opml`	是的
`RSS_UPDATE_INTERVAL`	馈送更新间隔（分钟）	`1`	没有
OpenAI配置
`OPENAI_API_KEY`	用于嵌入的OpenAI API密钥	-	否*

* 仅语义搜索功能需要。所有其他功能都可以在没有它的情况下工作。

Claude桌面配置

对于本地开发，请使用内置的dist文件夹：

{
  "mcpServers": {
    "rss": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_rss/dist/index.js"],
      "env": {
        "OPML_FILE_PATH": "/path/to/your/feeds.opml",
        "DB_HOST": "localhost",
        "DB_PORT": "5433",
        "DB_USER": "mcp_user",
        "DB_PASSWORD": "123456",
        "DB_NAME": "mcp_rss",
        "RSS_UPDATE_INTERVAL": "60",
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

通过npm进行全局安装：

{
  "mcpServers": {
    "rss": {
      "command": "npx",
      "args": ["mcp_rss"],
      "env": {
        "OPML_FILE_PATH": "/path/to/your/feeds.opml",
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

MCP工具参考

该服务器提供了8个强大的RSS源管理工具：

代币效率指南

所有列表/搜索工具现在都支持超高效的令牌使用：

默认行为：仅返回标题和元数据（无摘录，无内容）
可选摘录：设置 includeExcerpt: true 用于内容预览（适度使用令牌）
完整内容：设置 includeContent: true 获取完整的文章文本（高令牌使用率）
按需内容：使用 get_article_full 按ID获取特定文章（最有效）

推荐的工作流程（节省90%以上的代币）：

仅通过以下方式浏览标题 get_content 或 search_articles （默认设置）
仅从标题中识别有趣的文章
可选择获取边缘案例的摘录 includeExcerpt: true
使用获取完整内容 get_article_full 仅适用于选定的文章

令牌使用情况比较：

仅标题：每篇文章约50-100个代币
标题+摘录：每篇文章约150-300个标记
标题+完整内容：每篇文章约1000-5000个代币

1.获取内容

获取具有基本过滤和分页功能的文章。 首先返回最新文章 （按pubDate DESC排序）。

使用此功能：

浏览最近的文章
检查未读文章
按状态或来源进行简单筛选
特定时间段的日期范围筛选

令牌效率：

默认情况下，只返回标题和元数据（令牌效率最高）
集 includeExcerpt: true 添加内容预览
集 includeContent: true 获取文章全文
为了获得最佳效率：只浏览标题，然后使用 get_article_full 针对特定文章

参数：

参数	类型	描述	默认值
`statuses`	`string[]`	按状态筛选： `"unread"`, `"read"`, `"favorite"`, `"archived"`	所有状态
`source`	`string`	按源标题筛选	所有源
`limit`	`number`	要退回的文章数量	`10`
`offset`	`number`	分页偏移量	`0`
`favoriteBlogsOnly`	`boolean`	仅显示来自喜爱博客的文章	`false`
`prioritizeFavoriteBlogs`	`boolean`	首先显示最喜欢的博客文章	`false`
`includeContent`	`boolean`	包含完整的文章内容（使用更多标记）	`false`
`includeExcerpt`	`boolean`	包括文章摘录/预览	`false`
`startDate`	`string`	开始日期（ISO:YYY-MM-DD或YYYY-MM-DDHH:MM:ssZ）	-
`endDate`	`string`	结束日期（ISO格式）	-

示例（仅标题-最有效）：

{
  "statuses": ["unread"],
  "limit": 20
}

示例（包括日期范围和摘录）：

{
  "startDate": "2025-10-01",
  "endDate": "2025-10-25",
  "includeExcerpt": true,
  "limit": 15
}

示例（最喜欢的博客，内容完整）：

{
  "favoriteBlogsOnly": true,
  "limit": 5,
  "includeContent": true
}

响应（默认-仅标题，无摘录/内容）：

{
  "articles": [
    {
      "id": 123,
      "title": "Article Title",
      "link": "https://example.com/article",
      "pubDate": "2024-01-15T10:30:00Z",
      "fetchDate": "2024-01-15T11:00:00Z",
      "status": "unread",
      "feedTitle": "Engineering Blog",
      "feedCategory": "Technology"
    }
  ],
  "total": 150,
  "success": true
}

2.搜索_文章

具有关键字匹配、日期范围、类别和状态过滤器的高级搜索。 搜索标题和内容.

使用此功能：

查找关于特定主题的文章
基于日期的过滤
复杂的多条件搜索
特定类别搜索

参数：

参数	类型	描述	默认值
`keyword`	`string`	搜索词（不区分大小写，搜索标题+内容）	-
`category`	`string`	按饲料类别筛选	-
`statuses`	`string[]`	按文章状态筛选	全部
`startDate`	`string`	开始日期（ISO格式： `YYYY-MM-DD` 或 `YYYY-MM-DDTHH:mm:ssZ`)	-
`endDate`	`string`	结束日期（ISO格式）	-
`limit`	`number`	结果数量	`20`
`offset`	`number`	分页偏移量	`0`
`includeContent`	`boolean`	包含完整的文章内容（使用更多标记）	`false`

例子：

{
  "keyword": "kubernetes",
  "category": "Engineering",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "statuses": ["unread"],
  "limit": 10
}

3.语义研究

基于人工智能的语义搜索 使用OpenAI嵌入。即使没有精确的关键字匹配，也能查找概念上相似的文章。

使用此功能：

自然语言查询
查找相关概念
研究与发现
主题探索

要求：

OPENAI_API_KEY 必须设置
仅适用于2020年以后的文章
如果API密钥丢失（正常失败），则自动禁用

参数：

参数	类型	描述	默认值
`query`	`string`	自然语言搜索查询（必填）	-
`includeContent`	`boolean`	包含完整的文章内容（使用更多标记）	`false`
`limit`	`number`	结果数量	`10`
`statuses`	`string[]`	按文章状态筛选	全部
`category`	`string`	按饲料类别筛选	-

例子：

{
  "query": "how to optimize database performance and reduce query latency",
  "limit": 5,
  "statuses": ["unread"]
}

它是如何工作的：

使用OpenAI将查询转换为1536维向量
使用pgvector余弦相似度与文章嵌入进行比较
返回按相关性排序的语义相似的文章

4.获取信息

获取 今天未读的文章 按类别分组。非常适合日常阅读工作流程。筛选条件 发布日期 （pubDate），不获取日期。

使用此功能：

上午简报会
每日追赶
分类有序阅读
今天发表的文章（基于pubDate）

参数：

参数	类型	描述	默认值
`limit`	`number`	每个类别的最大文章数	`5`
`includeContent`	`boolean`	包含完整的文章内容（使用更多标记）	`false`

例子：

{
  "limit": 5
}

答复： 按类别分组的文章，今天每个类别最多可提取N篇文章。

5.每周订阅

新获取过去7天内最喜欢的文章（仅标题）。非常适合每周查看书签内容。

使用此功能：

每周阅读清单
查看过去一周保存的文章
跟踪重要书签内容
快速概述您最近发现的有价值的东西

参数： 无

例子： 无需参数，只需调用该工具即可。

答复：

{
  "articles": [
    {
      "id": 789,
      "title": "Optimizing PostgreSQL for High Write Throughput",
      "link": "https://engineering.example.com/postgres-optimization",
      "pubDate": "2025-10-22T14:30:00Z",
      "fetchDate": "2025-10-22T15:00:00Z",
      "status": "favorite",
      "feedTitle": "Engineering at Example",
      "feedCategory": "Database"
    },
    {
      "id": 654,
      "title": "Building Resilient Microservices with Circuit Breakers",
      "link": "https://blog.example.com/circuit-breakers",
      "pubDate": "2025-10-20T09:15:00Z",
      "fetchDate": "2025-10-20T10:00:00Z",
      "status": "favorite",
      "feedTitle": "Tech Blog",
      "feedCategory": "Architecture"
    }
  ],
  "total": 2,
  "success": true
}

特征：

返回过去7天内发表的标记为“收藏”的文章
按发布日期排序（最新者优先）
超代币效率-仅限标题和元数据
默认情况下没有摘录或内容
使用 get_article_full 阅读任何文章的全部内容

6.获取_条_满

按ID获取完整的文章内容。使用此方法进行令牌高效阅读：首先浏览标题，然后仅获取您想要阅读的文章的完整内容。

使用此功能：

浏览标题后阅读全文
获取特定有趣文章的完整内容
令牌高效工作流程（浏览→ 选择→ read)

参数：

参数	类型	说明	必填
`articleId`	`number`	来自get_content/search_articles的文章ID	是

例子：

{
  "articleId": 123
}

答复：

{
  "articles": [
    {
      "id": 123,
      "title": "Complete Article Title",
      "content": "Full article content with all HTML and formatting...",
      "link": "https://example.com/article",
      "pubDate": "2024-01-15T10:30:00Z",
      "fetchDate": "2024-01-15T11:00:00Z",
      "status": "unread",
      "feedTitle": "Engineering Blog",
      "feedCategory": "Technology",
      "excerpt": "First 200 characters..."
    }
  ],
  "success": true
}

令牌高效工作流程：

1. get_content(limit=20) → Browse 20 titles/excerpts
2. Find interesting article with id=456
3. get_article_full(articleId=456) → Read full content
4. set_tag(articleId=456, status="favorite") → Save for later

7.获取资源

通过分页和过滤获取RSS提要源。对于数百个提要，分页对于避免令牌限制至关重要。

使用此功能：

发现可用资源
查找用于筛选的有效源名称
探索饲料类别
浏览喜爱的博客

参数：

参数	类型	描述	默认值
`limit`	`number`	要返回的源数量（建议的最大值：100）	`50`
`offset`	`number`	分页偏移量（例如，第2页为50）	`0`
`favoritesOnly`	`boolean`	仅显示最喜欢的博客	`false`
`category`	`string`	按类别筛选（不区分大小写，部分匹配）	所有类别

示例（第一页）：

{
  "limit": 50,
  "offset": 0
}

示例（仅限收藏夹）：

{
  "favoritesOnly": true,
  "limit": 20
}

示例（按类别筛选）：

{
  "category": "Engineering",
  "limit": 30
}

答复：

{
  "sources": [
    {
      "id": 1,
      "title": "Engineering at Meta",
      "category": "Engineering Blogs",
      "url": "https://engineering.fb.com/feed/",
      "isFavorite": true
    },
    {
      "id": 2,
      "title": "Netflix Tech Blog",
      "category": "Engineering Blogs",
      "url": "https://netflixtechblog.com/feed",
      "isFavorite": false
    }
  ],
  "total": 518,
  "success": true
}

分页示例：

Page 1: offset=0, limit=50   → Sources 1-50 of 518
Page 2: offset=50, limit=50  → Sources 51-100 of 518
Page 3: offset=100, limit=50 → Sources 101-150 of 518

8.设置标签

更新文章状态以管理您的阅读工作流程。

使用此功能：

将文章标记为已读
保存收藏夹
归档旧文章
管理读取队列

参数：

参数	类型	说明	必填
`articleId`	`number`	要更新的文章ID	是
`status`	`string`	新状态： `"unread"`, `"read"`, `"favorite"`, `"archived"`	是的

例子：

{
  "articleId": 123,
  "status": "favorite"
}

文章状态工作流

服务器支持全面的4状态工作流：

┌─────────┐
│ unread  │ ← New articles start here
└────┬────┘
     │
     ├──→ read      (marked as read)
     ├──→ favorite  (important/bookmarked)
     └──→ archived  (old/irrelevant)

矢量搜索和嵌入

嵌入是如何工作的

自动生成：在获取RSS文章时，服务器会自动为以下来源的文章生成嵌入 2020年以后
OpenAI集成：用途 text-embedding-3-small 模型（1536个维度）
去重：每篇文章只生成一次嵌入（通过URL检查）
优雅降级：如果 OPENAI_API_KEY 缺失或无效，服务器继续正常工作（跳过嵌入）

存储

嵌入存储为 vector(1536) 在PostgreSQL中使用pgvector扩展
启用快速余弦相似性搜索： ORDER BY embedding <=> query_vector

成本优化

只有2020年以后的文章才能获得嵌入（可在中配置 RssService.shouldGenerateEmbedding())
重复的项目被跳过（没有多余的API调用）
嵌入生成失败不会阻止文章保存

发展

项目结构

mcp_rss/
├── src/
│   ├── entities/           # TypeORM entities
│   │   ├── Article.ts      # Article entity with vector embeddings
│   │   └── Feed.ts         # RSS feed source entity
│   ├── services/
│   │   ├── OpmlService.ts  # OPML parsing
│   │   ├── RssService.ts   # RSS fetching + embedding generation
│   │   ├── McpService.ts   # MCP tool implementations
│   │   └── EmbeddingService.ts # OpenAI embedding wrapper
│   ├── config/
│   │   └── database.ts     # TypeORM + pgvector setup
│   └── index.ts            # MCP server entry point
├── docker-compose.yml      # PostgreSQL with pgvector
├── .env.example            # Environment template
└── package.json

建筑

npm run build        # Compile TypeScript
npm run watch        # Watch mode for development

测试

# Test database connection
docker-compose ps

# Test MCP server locally
node dist/index.js

# Debug with MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js

故障排除

数据库连接问题

错误： connect ETIMEDOUT

确保PostgreSQL正在运行： docker-compose ps
检查端口5433是否可用： lsof -i :5433
验证环境变量是否与docker compose设置匹配

OpenAI API错误

错误： 401 Incorrect API key

在验证您的API密钥https://platform.openai.com/api-keys
确保你有可用的学分
检查钥匙是否过期

未生成嵌入：

服务器在没有API密钥的情况下工作正常（跳过嵌入）
检查文章日期（只有2020+的文章才能嵌入）
在控制台日志中查找错误

MCP服务器问题

服务器未出现在Claude Desktop中：

检查Claude Desktop配置路径是否正确
验证 dist/index.js 存在（运行 npm run build)
配置更改后重新启动Claude Desktop
检查Claude Desktop日志是否有错误

性能提示

调整更新间隔：设置 RSS_UPDATE_INTERVAL 生产时间超过60分钟
限制嵌入生成：嵌入仅适用于2020年以后的文章+
使用分页：始终使用 offset 和 limit 对于大型结果集
数据库索引PostgreSQL会自动为向量列建立索引

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

TypeScript编译时没有错误(npm run build)
记录环境变量
新功能包括适当的错误处理

使用说明

MCP RSS

特性

安装

先决条件

Docker Compose快速入门

数据库设置

配置

环境变量

Claude桌面配置

MCP工具参考

代币效率指南

1.获取内容

2.搜索_文章

3.语义研究

4.获取信息

5.每周订阅

6.获取_条_满

7.获取资源

8.设置标签

文章状态工作流

矢量搜索和嵌入

嵌入是如何工作的

存储

成本优化

发展

项目结构

建筑

测试

故障排除

数据库连接问题

OpenAI API错误

MCP服务器问题

性能提示

许可证

贡献

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Laravel文档聚合工具