Content
# rsshub-mcp
Weibo/Snowball Statement Observation MCP Server. Encapsulates RSSHub data acquisition capabilities into standardized MCP tools, allowing AI clients to directly query social media posts, manage and monitor accounts, and search historical content.
## Features
- Get the latest posts from Weibo/Snowball users
- Account monitoring management (add, delete, query)
- Full polling of all enabled accounts
- Post search and statistics
- Cookie health check
- RSSHub service status check
## Installation
```bash
# Clone the project
git clone <repo-url> rsshub-mcp
cd rsshub-mcp
# Install (recommended in conda or venv environment)
pip install -e .
# Development installation (including pytest)
pip install -e ".[dev]"
```
Requires Python >= 3.10.
## Configuration
### Method 1: YAML Configuration File
Copy `config.example.yaml` to `config.yaml` and edit:
```bash
cp config.example.yaml config.yaml
```
Main configuration items:
```yaml
rsshub_base_url: "http://localhost:1200"
access_key: "your-access-key-here"
weibo_cookies: ""
xueqiu_cookies: ""
db_path: "data/social_posts.duckdb"
accounts_file: "data/accounts.json"
transport: "stdio"
```
### Method 2: Environment Variables
All configuration items support environment variables with the `RSSHUB_MCP_` prefix:
```bash
export RSSHUB_MCP_RSSHUB_BASE_URL="http://localhost:1200"
export RSSHUB_MCP_ACCESS_KEY="your-key"
export RSSHUB_MCP_WEIBO_COOKIES="your-weibo-cookie"
export RSSHUB_MCP_XUEQIU_COOKIES="your-xueqiu-cookie"
```
### Configuration Priority
CLI parameters > YAML file > environment variables > built-in defaults
## Docker Deployment (RSSHub Backend)
The project comes with `docker-compose.yml`, one-click to start RSSHub + Redis:
```bash
# Copy environment variable template
cp .env.example .env
# Edit .env, fill in ACCESS_KEY and Cookie
# Generate random ACCESS_KEY: openssl rand -hex 16
# Start
docker compose up -d
# Verify RSSHub availability
curl http://localhost:1200/healthz
```
RSSHub listens on `localhost:1200`, Redis only communicates internally and does not expose ports.
See [COOKIE_GUIDE.md](COOKIE_GUIDE.md) for Weibo/Snowball Cookie.
## MCP Client Access
### OpenCode
Add to the `mcp` section of `opencode.json`:
```json
{
"mcp": {
"rsshub": {
"type": "local",
"command": ["python", "-m", "rsshub_mcp", "--transport", "stdio"]
}
}
}
```
If the project is not in PATH, specify the full path:
```json
{
"mcp": {
"rsshub": {
"type": "local",
"command": ["python", "-m", "rsshub_mcp", "--transport", "stdio"],
"cwd": "/path/to/rsshub-mcp"
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"rsshub": {
"command": "python",
"args": ["-m", "rsshub_mcp", "--transport", "stdio"],
"cwd": "/path/to/rsshub-mcp"
}
}
}
```
### Cursor
Add the same stdio configuration to Cursor MCP settings. Fill in command `python`, args `-m rsshub_mcp --transport stdio`, and project cwd.
## Tool List
There are 11 MCP tools, divided into four groups.
### Post Retrieval
| Tool | Parameters | Description |
|------|------------|-------------|
| `weibo_get_posts` | `uid` (str, required), `limit` (int, default 20) | Get the latest posts from Weibo users. uid is a pure digital UID |
| `xueqiu_get_posts` | `user_id` (str, required), `type` (int, default 10), `limit` (int, default 20) | Get Snowball user posts. type: 0=original, 2=long article, 4=Q&A, 9=hot, 11=trade, 10=all |
| `run_poll` | `platform` (str, optional) | Poll all enabled accounts in full. platform can be filled with "weibo" or "xueqiu" for filtering |
### Account Management
| Tool | Parameters | Description |
|------|------------|-------------|
| `add_account` | `platform` (str), `uid` (str), `name` (str), `category` (str, default "default") | Add monitoring account. platform is "weibo" or "xueqiu" |
| `remove_account` | `platform` (str), `uid` (str) | Remove monitoring account |
| `list_accounts` | `platform` (str, optional) | List all monitoring accounts, can be filtered by platform |
### Search and Statistics
| Tool | Parameters | Description |
|------|------------|-------------|
| `search_posts` | `keyword` (str, optional), `platform` (str, optional), `author` (str, optional), `days` (int, default 7) | Search collected posts. Supports keyword, platform, author, time range combination filtering |
| `get_stats` | None | Get collection statistics: total posts, posts per platform, and last collection time |
### Management Tools
| Tool | Parameters | Description |
|------|------------|-------------|
| `check_cookies` | None | Check Weibo/Snowball Cookie health status (valid/configured/not_set/expired/error) |
| `extract_uid` | `url` (str, required) | Extract user UID from Weibo or Snowball URL, return platform and ID |
| `check_rsshub_health` | None | Check if RSSHub service is available |
## Run
```bash
# stdio mode (MCP client direct connection, default)
rsshub-mcp --transport stdio
# HTTP mode (independent service)
rsshub-mcp --transport streamable-http --port 8000
# Specify configuration file
rsshub-mcp --config /path/to/config.yaml --transport stdio
```
Can also run directly using Python module:
```bash
python -m rsshub_mcp --transport stdio
```
## Project Structure
```
rsshub-mcp/
src/rsshub_mcp/
__main__.py # Entry
server.py # MCP server + 11 tools
config.py # Configuration loading
rsshub_client.py # RSSHub HTTP client
parser.py # RSS XML parsing
db.py # DuckDB storage
account_manager.py # Monitoring account management
cookie_manager.py # Cookie health check
tests/
config.example.yaml
docker-compose.yml
.env.example
COOKIE_GUIDE.md
```
## Development
```bash
# Run tests
pytest -v
# Code check
ruff check src/
```
## License
MIT
