Content
# WeChat Official Account MCP Server
A fully functional WeChat Official Account management MCP server that provides complete management features such as authentication, media management, drafts, and publishing.
## Features
### Account Type Support
- **Service Account**: Supports all features (authentication, media, drafts, publishing)
- **Subscription Account (Authenticated)**: Supports all features (authentication, media, drafts, publishing)
- **Subscription Account (Unauthenticated)**: Supports authentication, media, and drafts, **does not support publishing**
> **Note**: The publishing service (`wechat_publish`) is only available for authenticated official accounts and service accounts. Unauthenticated subscription accounts cannot use the publishing feature.
### MCP Tools
1. **Authentication Management** (`wechat_auth`)
- Configure WeChat Official Account AppID, AppSecret
- Obtain and refresh Access Token
- View current configuration
2. **Media Management** (`wechat_media_upload`)
- Upload temporary media (images, audio, video, thumbnails)
- Retrieve temporary media
- Supports file path or Base64 encoded data upload
3. **Image Upload for Articles** (`wechat_upload_img`)
- Upload images required for articles
- Does not count against media library limits
- Returns directly usable image URL
4. **Permanent Media Management** (`wechat_permanent_media`)
- Upload, retrieve, delete permanent media
- Get media list and statistics
- Supports images, audio, video, thumbnails, and articles
5. **Draft Management** (`wechat_draft`)
- Create, retrieve, delete, update article drafts
- Get draft list and statistics
- Supports drafts for multiple articles
6. **Publishing Management** (`wechat_publish`)
- Publish drafts to WeChat Official Account
- Get publishing status
- Delete published articles
- Get publishing list
- **Permission Requirement**: Only authenticated official accounts and service accounts can use the publishing feature
7. **Template Tool** (`wechat_template`)
- Generate HTML content for official account articles based on P-site style templates
- Supports various content blocks: title, chapters, statistics, quotes, code, progress bars, etc.
- When users say "use P-site template" or "use phub template," the AI can automatically use this tool
- See [Template Usage Guide](docs/template_usage.md) for details
### MCP Resources
1. **P-site Style Template** (`template://phub_template`)
- HTML template for official account articles styled like P-site (Pornhub)
- AI can read template content to understand structure
- Used with the template tool to generate HTML articles that match the style
## Project Structure
```
wechat_official_account_mcp/
├── main.py # Main file for MCP server
├── main_mcp.py # Entry point for MCP server (optional)
├── tools/ # MCP tools
│ ├── auth.py # Authentication tool
│ ├── media.py # Media management tool
│ ├── draft.py # Draft management tool
│ └── publish.py # Publishing tool
│
├── shared/ # Shared modules
│ ├── storage/ # Storage management
│ │ ├── auth_manager.py # Authentication manager
│ │ └── storage_manager.py # Storage manager
│ └── utils/ # Utility classes
│ └── wechat_api_client.py # WeChat API client
├── data/ # Data directory (not submitted to git)
│ └── auth_config.json # Authentication configuration (local storage)
├── Dockerfile # Docker build file
└── docker-compose.yml # Docker Compose configuration
```
## Installation
### 1. Clone the Project
```bash
git clone <repository-url>
cd wechat_official_account_mcp
```
### 2. Install Dependencies
```bash
pip install mcp requests python-dotenv aiohttp
```
Or use requirements.txt (if available):
```bash
pip install -r requirements.txt
```
### 3. Configure Environment Variables
Create a `.env` file:
```env
# Basic configuration for WeChat Official Account (required)
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```
## Usage
### Account Permission Explanation
Before using the publishing feature, please confirm your official account type:
- ✅ **Service Account**: Can use all features, including publishing
- ✅ **Authenticated Subscription Account**: Can use all features, including publishing
- ❌ **Unauthenticated Subscription Account**: Can use authentication, media, and drafts, but **cannot use publishing**
If your account does not support the publishing feature, calling the publishing interface will return the corresponding error message.
### Start the MCP Server
The MCP server communicates with the client via stdio:
```bash
python main.py
```
Or use the entry file:
```bash
python mcp_server.py
```
### Run with Docker
#### Using Docker Compose (Recommended)
```bash
# Build and start
docker compose up -d
# View logs
docker compose logs -f
# Stop the service
docker compose down
```
#### Using Docker
```bash
# Build the image
docker build -t wechat-mcp .
# Run the container
docker run -it --rm \
-v $(pwd)/data:/app/data \
-e WECHAT_APP_ID=your_app_id \
-e WECHAT_APP_SECRET=your_app_secret \
wechat-mcp
```
### Configure MCP Client
#### Claude Desktop
Edit the configuration file (Windows):
```
%APPDATA%\Claude\claude_desktop_config.json
```
Add the configuration:
```json
{
"mcpServers": {
"wechat-official-account": {
"command": "python",
"args": ["C:\\path\\to\\wechat_official_account_mcp\\main.py"],
"env": {
"WECHAT_APP_ID": "your_app_id",
"WECHAT_APP_SECRET": "your_app_secret"
}
}
}
}
```
