mcp-server-weread

<p align="center">
  <img src="https://cdn.canghecode.com/blog/%E5%BE%AE%E4%BF%A1%E8%AF%BB%E4%B9%A6MCP%20bac.png" alt="MaxKB" width="300" />
</p>

<h3 align="center">MCP Server for WeChat Reading</h3>

<p align="center">
  <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/github/license/freestylefly/mcp-server-weread?color=rgb(25%2C%20121%2C%20255)" alt="The MIT License"></a>
  <a href="https://github.com/freestylefly/mcp-server-weread/fork"><img src="https://img.shields.io/github/forks/freestylefly/mcp-server-weread?color=green" alt="Forks"></a>
  <a href="https://canghecode.com/"><img src="https://img.shields.io/badge/Introduction-Official%20Website-green" alt="Official"></a>
  <a href="https://github.com/freestylefly/mcp-server-weread"><img src="https://img.shields.io/github/stars/freestylefly/mcp-server-weread?style=flat-square&color=rgb(25%2C%20121%2C%20255)" alt="Stars"></a>
  <a href="https://mp.weixin.qq.com/s/NQslbUBgWIBMyvTIa3PfYQ"><img src="https://img.shields.io/badge/WeRead%20MCP-Tutorial-blue" alt="Experience"></a>
</p>

---

**WeChat Reading MCP Server** is a tool that provides MCP (Model Context Protocol) services for WeChat Reading. It allows you to feed your WeChat Reading books, notes, and highlights data to LLM clients that support the MCP protocol, such as Cursor and Claude Desktop, enabling powerful integrations and enhanced knowledge retrieval.

## Key Features

*   **Bookshelf Access:** Retrieve your entire WeChat Reading bookshelf information.
*   **Book Search:** Search your bookshelf for specific books using keywords.
*   **Notes & Highlights Extraction:**  Fetch all your notes and highlights for a given book, organized by chapter.
*   **Popular Reviews:** Access popular book reviews from WeChat Reading.
*   **MCP Compatibility:** Seamless integration with LLM clients supporting the MCP protocol.
*   **Structured Data:** Returns data in a structured format optimized for LLM understanding.

## Core Tools (MCP Endpoints)

This server exposes the following tools, which can be called by MCP-compatible LLM clients:

1.  **`get_bookshelf`**: Retrieves all books from the user's WeChat Reading bookshelf.
    *   Returns basic book information, including title, author, translator, and category.

2.  **`search_books`**: Searches the user's bookshelf for books matching a given keyword.
    *   Supports fuzzy and exact matching.
    *   Option to include detailed book information in the results.
    *   Configurable maximum number of results.

3.  **`get_book_notes_and_highlights`**: Retrieves all highlights and notes for a specific book.
    *   Organizes results by chapter.
    *   Supports filtering by highlight style.
    *   Returns structured data suitable for LLM consumption.

4.  **`get_book_best_reviews`**: Retrieves popular book reviews for a specific book.
    *   Configurable number of reviews to return.
    *   Supports pagination.
    *   Includes review rating, number of likes, and reviewer information.

## Installation & Usage

### Prerequisites

*   Node.js 16.x or higher
*   WeChat Reading account and valid cookie

### Installation Instructions

Refer to the following resources for detailed installation instructions:

*   [Using WeChat Reading MCP in Cursor to Build a Private Library (Chinese)](https://mp.weixin.qq.com/s/NQslbUBgWIBMyvTIa3PfYQ)
*   [Weread MCP Server Usage Guide (Chinese)](https://chenge.ink/article/post20250505)

### Integration with Claude Desktop

You can integrate this MCP server with Claude Desktop in several ways:

#### Method 1: Using `npx` (Recommended - Simplest)

1.  Open Claude Desktop.
2.  Go to Settings -> MCP Configuration.
3.  Add a new tool using the following JSON configuration:

    ```json
    {
      "mcpServers": {
        "mcp-server-weread": {
          "command": "npx",
          "args": ["-y", "mcp-server-weread"],
          "env": {
            // Option 1: Using Cookie Cloud (Recommended)
            "CC_URL": "https://cc.chenge.ink",  // Cookie Cloud URL
            "CC_ID": "your_cookie_cloud_id",    // Cookie Cloud ID
            "CC_PASSWORD": "your_cookie_cloud_password" // Cookie Cloud Password

            // Option 2: Directly Provide Cookie (Less Secure)
            // "WEREAD_COOKIE": "your_wechat_reading_cookie"
          }
        }
      }
    }
    ```

#### Method 2: Global Installation

1.  Install the package globally:

    ```bash
    npm install -g mcp-server-weread
    ```

2.  Use the following configuration in Claude Desktop:

    ```json
    {
      "mcpServers": {
        "mcp-server-weread": {
          "command": "mcp-server-weread",
          "env": {
            // Configure environment variables as in Method 1
          }
        }
      }
    }
    ```

> **Tip:** Providing environment variables directly in the Claude configuration is more convenient than using a `.env` file.  This approach is recommended.

## CookieCloud Configuration

To address the issue of frequent cookie expiration and the need to re-acquire and update environment variables, this project supports the [CookieCloud](https://github.com/easychen/CookieCloud) service for automatic cookie synchronization and updates. CookieCloud is an open-source cross-browser cookie synchronization tool that supports self-hosting.

### Configuration Steps:

1.  **Install the Browser Extension:**
    *   Edge Store: [CookieCloud for Edge](https://microsoftedge.microsoft.com/addons/detail/cookiecloud/bffenpfpjikaeocaihdonmgnjjdpjkeo)
    *   Chrome Store: [CookieCloud for Chrome](https://chromewebstore.google.com/detail/cookiecloud/ffjiejobkoibkjlhjnlgmcnnigeelbdl)

2.  **Configure the CookieCloud Extension:**
    *   **Server Address:** Use the default server `https://cc.chenge.ink` or enter your self-hosted server address.
    *   Click "Generate Password Automatically."
    *   Enter "weread" in the "Synchronize Domain Keywords" field.
    *   Click "Save" and then "Manual Sync" to ensure the configuration takes effect.
    *   **[Optional]** To automatically keep the extension alive, enter `https://weread.qq.com` in the "Keep Alive" field. The extension will automatically refresh the cookie.

3.  **Configure CookieCloud Variables in MCP JSON:**

    ```json
    {
      "CC_URL": "your_cookiecloud_server_address", // or use the default: "https://cc.chenge.ink"
      "CC_ID": "your_cookiecloud_user_uuid",
      "CC_PASSWORD": "your_cookiecloud_password"
    }
    ```

    **Note:** When CookieCloud is configured, the system will prioritize using CookieCloud to obtain the cookie. If CookieCloud fails, it will fall back to using the `WEREAD_COOKIE` environment variable.

## Cookie Acquisition Method

You can obtain the WeChat Reading cookie using the following steps:

1.  Log in to the [WeChat Reading web version](https://weread.qq.com/) using Chrome.
2.  Press F12 to open the developer tools and switch to the "Network" tab.
3.  Refresh the page and find a request to `weread.qq.com` in the request list.
4.  In the "Headers" section, find the "Cookie" field and copy its complete content.
5.  Add the copied content to the `WEREAD_COOKIE` variable in the MCP JSON configuration or a `.env` file.

## Usage Examples (LLM Interactions)

The following are examples of how to interact with an LLM using this MCP server:

**Get Bookshelf Information**

User: Show me my WeChat Reading bookshelf.
LLM: I will