Content
# WeChat Reading MCP Server
The WeChat Reading MCP Server is a lightweight server that bridges WeChat Reading data and Claude Desktop, allowing you to seamlessly access your notes and reading data from WeChat Reading within Claude.
## Installation and Usage
### Environment Preparation
1. Ensure that your system has Node.js (v16+) installed.
2. Clone this repository: `git clone https://github.com/yourusername/mcp-server-weread.git`
3. Navigate to the project directory: `cd mcp-server-weread`
4. Install dependencies: `npm install` (if the download is slow, you can use: `npm install --registry=https://registry.npmmirror.com`)
### Obtain WeChat Reading Cookie
1. Log in to the WeChat Reading web version in your browser: https://weread.qq.com/
2. Open the browser developer tools (F12 or right-click and inspect).
3. Switch to the "Application" tab.
4. Find "Cookies" under "Storage" on the left side.
5. Select "https://weread.qq.com".
6. Find and copy all cookies (you can select all and copy all values).
### Configure Environment Variables
1. In the project root directory, edit the `.env` file.
2. Set the WeChat Reading Cookie: `WEREAD_COOKIE=your_copied_cookie_value`.
### Start the Server
1. Compile the code: `npm run build`.
2. Start the server: `node build/index.js`.
### Configure in MCP Client
Taking Cursor AI as an example, add the following to the `~/.cursor/mcp.json` file:
```json
{
"mcpServers": {
"mcp-server-weread": {
"command": "node",
"args": ["/path/to/mcp-server-weread/build/index.js"],
"env": {
"WEREAD_COOKIE": "your_wechat_reading_cookie"
}
}
}
}
```
Replace `/path/to/mcp-server-weread` with the actual installation path and set the correct cookie value.
## Supported Features
The server provides the following tools:
1. **get_bookshelf** - Retrieve the user's complete bookshelf information.
2. **get_notebooks** - Retrieve a list of books with notes.
3. **get_book_notes** - Retrieve all note content for a specific book.
4. **get_book_info** - Retrieve detailed information about a book.
5. **search_notes** - Search for content containing specific keywords in all notes.
6. **get_recent_reads** - Retrieve the books the user has recently read and related data.
## Usage Examples
In an AI client that supports MCP (such as Claude Desktop), you can:
1. Request: "Help me check what books are on my bookshelf."
2. Request: "I want to see the notes for the book 'Thinking, Fast and Slow'."
3. Request: "Help me find content about 'cognitive bias' in my notes."
4. Request: "Get the books I have read recently."
---
# WeChat Reading MCP Server Design Plan
## Product Positioning and Goals
**Product Name**: WeRead MCP Server
**Product Positioning**: A lightweight server that acts as a bridge between WeChat Reading and Claude Desktop, enabling deep interaction with reading notes and AI.
**Core Goals**:
1. Achieve real-time retrieval and formatting of WeChat Reading data.
2. Seamlessly integrate with Claude Desktop via the MCP protocol.
3. Support in-depth conversations and knowledge extraction based on reading notes.
4. Build a complete "input-organize-settle" knowledge workflow.
**Value Proposition**:
- Transform fragmented reading notes into a systematic knowledge framework.
- Enhance understanding and application of reading content through AI assistance.
- Reduce the complexity of knowledge management, achieving lightweight knowledge accumulation.
- Improve reading efficiency and quality.
## System Architecture
```
+---------------+ +-----------------+ +------------------+
| | | | | |
| WeChat Reading Server | <--> | WeRead MCP Server | <--> | Claude Desktop |
| | | | | |
+---------------+ +-----------------+ +------------------+
```
### Features
- Lightweight design: No local database, real-time API calls.
- On-demand data retrieval: Call relevant APIs only when requested by the user.
- Stateless service: No complex session state maintenance.
- Security: Manage cookies through environment variables to avoid plaintext storage.
## Features and Use Cases
### Core Features
1. **Book and Note Browsing**
- Retrieve user bookshelf information.
- Retrieve a list of books with notes.
- Retrieve detailed information about specific books.
2. **Note Content Retrieval and Processing**
- Retrieve all notes (highlights, comments) for specific books.
- Organize note content by chapter.
- Search note content based on keywords.
3. **Reading Data Retrieval**
- Retrieve recent reading history.
- Retrieve reading progress information.
4. **AI-Assisted Analysis**
- Analyze note content through Claude.
- Extract key points and insights.
- Relate concepts from different books.
### Use Cases
#### Scenario 1: In-Depth Reading Analysis and Discussion
1. **Start a Conversation**: The user opens Claude Desktop and starts a new conversation.
2. **Select a Book**: The user requests: "Help me check the books I have been reading recently."
3. **Retrieve Notes**: The user says: "I want to discuss the notes for the book 'Thinking, Fast and Slow'."
4. **In-Depth Discussion**: After Claude displays the notes, the user can request: "Help me analyze the main points about cognitive bias in these notes."
5. **Relate Thoughts**: The user can further request: "Compare these points with my notes in the book 'Beyond IQ'."
#### Scenario 2: Thematic Note Integration
1. **Thematic Search**: The user says: "Find all notes related to 'leadership'."
2. **Cross-Book Integration**: After the system finds relevant notes from multiple books, the user can request: "Help me integrate these viewpoints from different sources, identifying commonalities and differences."
3. **Knowledge Map**: The user says: "Based on these notes, help me build a knowledge framework for leadership."
#### Scenario 3: Writing and Creation Assistance
1. **Material Collection**: The user says: "I am writing an article about 'team building', find all my related reading notes."
2. **Structure Organization**: After retrieving the notes, the user can say: "Help me organize these materials into a logically clear article outline."
3. **Content Expansion**: The user says: "Based on this outline and my notes, help me expand the content of the second section."
## MCP Tools Implementation Checklist
### 1. Get Bookshelf Tool (get_bookshelf)
**Function**: Retrieve the user's complete bookshelf information.
**Parameters**: None
**Returns**: A formatted list of books, including titles, authors, and other basic information.
**Implementation Logic**:
```python
def get_bookshelf():
"""Retrieve the user's complete bookshelf information."""
# Directly call the get_bookshelf method from WeReadApi
weread_api = WeReadApi()
bookshelf_data = weread_api.get_bookshelf()
# Process returned data to extract useful information
books = []
if "books" in bookshelf_data:
for book in bookshelf_data["books"]:
books.append({
"bookId": book.get("bookId", ""),
"title": book.get("title", ""),
"author": book.get("author", ""),
"cover": book.get("cover", ""),
"category": book.get("category", ""),
"finished": book.get("finished", False),
"updateTime": book.get("updateTime", 0)
})
return {"books": books}
```
### 2. Get Notebooks List Tool (get_notebooks)
**Function**: Retrieve a list of all books with notes.
**Parameters**: None
**Returns**: A list of books with notes, sorted in order.
**Implementation Logic**:
```python
def get_notebooks():
"""Retrieve a list of all books with notes."""
# Directly call the get_notebooklist method from WeReadApi
weread_api = WeReadApi()
notebooks = weread_api.get_notebooklist()
# Process returned data to extract useful information
formatted_notebooks = []
for notebook in notebooks:
formatted_notebooks.append({
"bookId": notebook.get("bookId", ""),
"title": notebook.get("title", ""),
"author": notebook.get("author", ""),
"cover": notebook.get("cover", ""),
"noteCount": notebook.get("noteCount", 0),
"sort": notebook.get("sort", 0),
"bookUrl": weread_api.get_url(notebook.get("bookId", ""))
})
return {"notebooks": formatted_notebooks}
```
### 3. Get Book Notes Tool (get_book_notes)
**Function**: Retrieve all note content for a specific book.
**Parameters**: bookId (string) - Book ID.
**Returns**: Note content organized by chapter, including highlights and comments.
**Implementation Logic**:
```python
def get_book_notes(bookId):
"""Retrieve all note content for a specific book."""
weread_api = WeReadApi()
# 1. Get chapter information
chapter_info = weread_api.get_chapter_info(bookId)
# 2. Get highlights (bookmarks)
bookmarks = weread_api.get_bookmark_list(bookId) or []
# 3. Get comments/reviews
reviews = weread_api.get_review_list(bookId) or []
# 4. Get basic book information
book_info = weread_api.get_bookinfo(bookId) or {}
# Process chapter information
chapters = {}
for uid, chapter in chapter_info.items():
chapters[uid] = {
"title": chapter.get("title", ""),
"level": chapter.get("level", 0),
"chapterIdx": chapter.get("chapterIdx", 0)
}
# Process highlights and review data, organized by chapter
organized_notes = {}
# Add highlights
for bookmark in bookmarks:
chapter_uid = str(bookmark.get("chapterUid", ""))
if chapter_uid not in organized_notes:
organized_notes[chapter_uid] = {
"chapterTitle": chapters.get(chapter_uid, {}).get("title", "Unknown Chapter"),
"chapterLevel": chapters.get(chapter_uid, {}).get("level", 0),
"highlights": [],
"reviews": []
}
organized_notes[chapter_uid]["highlights"].append({
"text": bookmark.get("markText", ""),
"createTime": bookmark.get("createTime", 0),
"style": bookmark.get("style", 0)
})
# Add reviews
for review in reviews:
chapter_uid = str(review.get("chapterUid", ""))
if chapter_uid not in organized_notes:
organized_notes[chapter_uid] = {
"chapterTitle": chapters.get(chapter_uid, {}).get("title", "Unknown Chapter"),
"chapterLevel": chapters.get(chapter_uid, {}).get("level", 0),
"highlights": [],
"reviews": []
}
organized_notes[chapter_uid]["reviews"].append({
"content": review.get("content", ""),
"createTime": review.get("createTime", 0),
"type": review.get("type", 0)
})
# Organize final return data
return {
"bookInfo": {
"bookId": bookId,
"title": book_info.get("title", ""),
"author": book_info.get("author", ""),
"cover": book_info.get("cover", ""),
"url": weread_api.get_url(bookId)
},
"notes": organized_notes
}
```
### 4. Get Book Info Tool (get_book_info)
**Function**: Retrieve detailed information about a book.
**Parameters**: bookId (string) - Book ID.
**Returns**: Detailed information about the book, including title, author, and summary.
**Implementation Logic**:
```python
def get_book_info(bookId):
"""Retrieve detailed information about a book."""
weread_api = WeReadApi()
book_info = weread_api.get_bookinfo(bookId)
# Process and return formatted book information
formatted_info = {
"bookId": bookId,
"title": book_info.get("title", ""),
"author": book_info.get("author", ""),
"cover": book_info.get("cover", ""),
"intro": book_info.get("intro", ""),
"category": book_info.get("category", ""),
"publisher": book_info.get("publisher", ""),
"publishTime": book_info.get("publishTime", ""),
"isbn": book_info.get("isbn", ""),
"bookScore": book_info.get("newRating", {}).get("score", 0),
"url": weread_api.get_url(bookId)
}
return formatted_info
```
### 5. Search Notes Tool (search_notes)
**Function**: Search for content containing specific keywords in all notes.
**Parameters**: keyword (string) - Search keyword.
**Returns**: A list of notes matching the keyword, including source books and content.
**Implementation Logic**:
```python
def search_notes(keyword):
"""Search for content containing specific keywords in all notes."""
weread_api = WeReadApi()
# 1. Get all books with notes
notebooks = weread_api.get_notebooklist()
# 2. Iterate through each book's notes to find matching content
search_results = []
for notebook in notebooks:
bookId = notebook.get("bookId", "")
book_title = notebook.get("title", "")
# Get highlights
bookmarks = weread_api.get_bookmark_list(bookId) or []
# Get reviews
reviews = weread_api.get_review_list(bookId) or []
# Search highlight content
for bookmark in bookmarks:
mark_text = bookmark.get("markText", "")
if keyword.lower() in mark_text.lower():
search_results.append({
"bookId": bookId,
"bookTitle": book_title,
"chapterUid": bookmark.get("chapterUid", ""),
"type": "highlight",
"content": mark_text,
"createTime": bookmark.get("createTime", 0)
})
# Search review content
for review in reviews:
review_content = review.get("content", "")
if keyword.lower() in review_content.lower():
search_results.append({
"bookId": bookId,
"bookTitle": book_title,
"chapterUid": review.get("chapterUid", ""),
"type": "review",
"content": review_content,
"createTime": review.get("createTime", 0)
})
# Sort by time
search_results.sort(key=lambda x: x["createTime"], reverse=True)
return {"results": search_results, "keyword": keyword, "count": len(search_results)}
```
### 6. Recent Reads Tool (get_recent_reads)
**Function**: Retrieve the books the user has recently read and related data.
**Parameters**: None
**Returns**: A list of recently read books, including reading progress and time information.
**Implementation Logic**:
```python
def get_recent_reads():
"""Retrieve the books the user has recently read and related data."""
weread_api = WeReadApi()
# Get reading history data
history_data = weread_api.get_api_data()
# Extract and format recent reading data
recent_books = []
if "recentBooks" in history_data:
for book in history_data["recentBooks"]:
# Get reading information for each book
read_info = weread_api.get_read_info(book["bookId"])
recent_books.append({
"bookId": book.get("bookId", ""),
"title": book.get("title", ""),
"author": book.get("author", ""),
"cover": book.get("cover", ""),
"readingTime": read_info.get("readingTime", 0), # Reading duration (seconds)
"progress": read_info.get("progress", 0), # Reading progress (%)
"lastReadingDate": read_info.get("lastReadingDate", 0),
"noteCount": read_info.get("noteCount", 0),
"url": weread_api.get_url(book.get("bookId", ""))
})
return {"recentBooks": recent_books}
```
## Technical Implementation Considerations
1. **Environment Variable Management**
- Use .env files or system environment variables to manage sensitive information (Cookies).
- Support Cookie Cloud services to obtain the latest Cookies.
2. **Error Handling**
- A comprehensive exception handling mechanism, especially for API call failures.
- Cookie expiration reminders and automatic refresh mechanisms.
3. **Performance Optimization**
- Control API call frequency to avoid triggering limits.
- Consider short-term caching mechanisms to reduce duplicate calls.
4. **MCP Protocol Adaptation**
- Ensure tool input and output comply with Claude Desktop's MCP specifications.
- Provide clear tool descriptions and usage examples.
## Future Expansion Directions
1. **Add Note Export Functionality**
- Support exporting in various formats such as Markdown, JSON, etc.
- Facilitate knowledge accumulation and sharing.
2. **Add Note Statistical Analysis**
- Provide data visualization of reading and note-taking behaviors.
- Help users understand their reading patterns.
3. **Personalized Recommendations**
- Recommend related books or articles based on user reading history and note content.
- Help users expand their knowledge network.
4. **Knowledge Graph Construction**
- Automatically build a knowledge association network based on user reading content.
- Visualize the connections between different concepts and books.
5. **Multi-Platform Integration**
- Integrate data from other reading platforms (e.g., Kindle, Douban, etc.).
- Build a unified reading note management system.
