Content
# WeChat Reader MCP Server
WeChat Official Account Article Reader MCP Server
## 🚀 Features
- **Intelligent Article Extraction**: Extracts complete content and metadata from WeChat official account article URLs
- **Multiple Output Formats**: Supports Markdown and plain text output formats
- **Image Handling**: Option to include image links, supports lazy-loaded image recognition
- **Anti-Crawling Handling**: Uses Playwright browser automation technology to effectively bypass anti-crawling mechanisms
- **Resource Management**: Integrates proxy pool and Cookie pool management to improve crawling success rate
- **Intelligent Parsing**: Multiple selector strategies, compatible with various page structures and versions
- **Content Cleaning**: Automatically removes ads, sharing buttons, and other distracting elements, retaining core content
- **Error Recovery**: Intelligent error handling and status reporting mechanism
- **Content Optimization**: Automatically truncates response content to comply with token limits
## 📋 Applicable Scenarios
- 📝 **Article Content Extraction and Summary Generation**
- 🔍 **Content Source for RAG (Retrieval-Augmented Generation) Applications**
- 📊 **Official Account Content Analysis and Archiving**
- 🔔 **Information Monitoring and Data Collection**
## 🛠️ Installation
### Prerequisites
- Python 3.10+
- pip or uv package manager
### Installation Steps
1. Clone the project:
```bash
git clone <repository-url>
cd mcp-server-wechat-reader
```
2. Install dependencies:
```bash
# Using pip
pip install -e .
# Or using uv (recommended)
uv pip install -e .
```
3. Install development dependencies (optional):
```bash
# Using pip
pip install -e .[dev]
# Or using uv
uv pip install -e .[dev]
```
## 🎯 Usage
### Start the Server
```bash
# Run directly
python -m mcp_server_wechat_reader.server
# Or use the script
mcp-server-wechat-reader
```
### Configure in Cursor/Trae Client
To use WeChat Reader MCP Server in Cursor or Trae IDE, you need to add the corresponding server configuration in the IDE's MCP configuration file.
#### Configuration Steps
1. **Locate the MCP Configuration File**
- In Cursor/Trae, the MCP configuration file is usually located at:
- `~/.cursor/mcp.json` (Cursor)
- `~/.trae/mcp.json` (Trae)
- If the file does not exist, create it
2. **Add WeChat Reader Configuration**
Add the following configuration to the MCP configuration file (adjust according to your actual path):
```json
{
"mcpServers": {
"wechat-reader": {
"command": "/path/to/your/venv/bin/fastmcp",
"args": [
"run",
"/path/to/mcp-server-wechat-reader/src/mcp_server_wechat_reader/server.py"
]
}
}
}
```
#### Configuration Example (Based on Your Environment)
```json
{
"mcpServers": {
"wechat-reader": {
"command": "/Users/mac/Study/mcp-courseware-master/mcp-server-wechat-reader/.venv/bin/fastmcp",
"args": [
"run",
"/Users/mac/Study/mcp-courseware-master/mcp-server-wechat-reader/src/mcp_server_wechat_reader/server.py"
]
}
}
}
```
#### Path Description
- **command**: Points to the `fastmcp` executable in your Python virtual environment
- If you use `uv`, the path might be: `/path/to/project/.venv/bin/fastmcp`
- If you use `pip`, the path might be: `/path/to/project/.venv/bin/fastmcp`
- **args**: Contains the `run` command and the full path to the server script
#### Verify Configuration
1. After saving the configuration file, restart Cursor/Trae IDE
2. In the chat interface, you should see the available MCP tools
3. Enter `/tools` or view the tool list to confirm that the `read_article` tool is loaded
#### Usage Example
After successful configuration, you can use it directly in the IDE:
```
Please help me read this article: https://mp.weixin.qq.com/s/xxxxxxxxx
```
Or use the tool calling format:
```json
{
"url": "https://mp.weixin.qq.com/s/xxxxxxxxx",
"output_format": "markdown",
"include_images": false
}
```
### Using FastMCP Development Tools
```bash
# Debug with MCP Inspector
fastmcp dev src/mcp_server_wechat_reader/server.py
# View tool list
fastmcp install claude-desktop src/mcp_server_wechat_reader/server.py --preview
```
### Tool Usage Examples
#### read_article_tool
Extract content from a WeChat official account article URL:
```json
{
"url": "https://mp.weixin.qq.com/s/xxxxxxxxx",
"output_format": "markdown",
"include_images": false
}
```
**Parameter Description:**
- `url` (required): The complete URL of the WeChat official account article
- `output_format` (optional): Output format, "markdown" or "text", default "markdown"
- `include_images` (optional): Whether to include image links, default false
**Return Example:**
```json
{
"title": "Article Title",
"author": "Author Name",
"official_account": "Official Account Name",
"publish_date": "2024-11-04",
"content": "Formatted article content...",
"source_url": "https://mp.weixin.qq.com/s/xxxxxxxxx"
}
```
## 🏗️ Project Structure
```
mcp-server-wechat-reader/
├── src/
│ └── mcp_server_wechat_reader/
│ ├── server.py # Main server file
│ ├── tools/
│ │ ├── __init__.py
│ │ └── reader.py # read_article tool implementation
│ └── utils/
│ ├── __init__.py
│ ├── api_client.py # Web crawling client
│ ├── formatters.py # Response formatting tool
│ └── errors.py # Error handling module
├── tests/
├── pyproject.toml
└── README.md
```
## ⚙️ Configuration
### Environment Variables
The server supports the following environment variables to enhance crawling capabilities:
- `PROXY_POOL_URL` (optional): URL of the proxy pool service, format like `http://proxy-service.com/api/proxy`
- `COOKIE_POOL_URL` (optional): URL of the Cookie pool service, format like `http://cookie-service.com/api/cookies`
- `DATABASE_URL` (optional): Database connection string for data persistence
**Configuration Example**:
```bash
export PROXY_POOL_URL="http://your-proxy-pool.com/api/proxy"
export COOKIE_POOL_URL="http://your-cookie-pool.com/api/cookies"
```
**Note**: These services are optional. If not configured, the server will use the built-in basic crawling strategy.
### Request Configuration
The server has built-in configurations to optimize crawling effects:
- **Request Interval**: 2 seconds (avoid frequent requests)
- **Request Timeout**: 60 seconds
- **User-Agent Rotation**: Automatically rotate browser identifiers
- **Cookie Management**: Automatically manage session state
## 🔧 Development
### Local Development
```bash
# Start the development server
fastmcp dev src/mcp_server_wechat_reader/server.py
# Run tests
pytest tests/
# Code formatting
black src/ tests/
# Type checking
mypy src/
```
### Adding New Features
1. Add shared functionality in `utils/`
2. Implement new tools in `tools/`
3. Register the tool in `server.py`
4. Add corresponding tests
## ⚠️ Usage Notice
### Legal Compliance
- Please comply with the WeChat platform's terms of use and relevant laws and regulations
- Respect copyright and use crawled content reasonably
- It is recommended to use it only for personal learning and research purposes
### Technical Limitations
- Some articles may not be accessible due to privacy settings or deletion
- WeChat's anti-crawling mechanisms may cause temporary access restrictions
- It is recommended to control the request frequency to avoid pressure on WeChat servers
### Best Practices
- Use valid WeChat official account article links (mp.weixin.qq.com)
- Choose the appropriate output format as needed
- Handle possible network errors and anti-crawling interceptions
- Consider using a proxy pool in a production environment
## 🐛 Troubleshooting
### Common Errors
1. **Invalid URL**
- Ensure the URL is a WeChat official account article link
- Check if the URL format is correct
2. **Network Request Failed**
- Check the network connection
- Consider using a proxy
- Retry later
3. **Blocked by Anti-Crawling**
- Reduce the request frequency
- Change the IP address
- Wait for a while and retry
4. **Parsing Failed**
- Check if the article is displayed normally
- May need to update the parsing logic
## 📄 License
This project is licensed under the MIT License. See the LICENSE file for details.
## 🤝 Contribution
Welcome to submit Issues and Pull Requests!
1. Fork this project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📞 Support
If you encounter problems during use, please:
1. Check the troubleshooting section of this README
2. Search for existing Issues
3. Create a new Issue and provide detailed information
---
**Start using WeChat Reader MCP Server to read WeChat articles!** 🎉
