夏颜

夏颜 MCP Server is a Python-based gateway that lets you publish Markdown content to WeChat Official Accounts via MCP (Model Context Protocol). It supports multiple themes, automatic media handling, and a structured toolset to manage publishing workflows directly from your MCP-enabled AI assistants.

How to use

You connect to the 夏颜 MCP Server from an MCP client that supports stdio-based servers. The server runs locally and accepts commands from your client to publish Markdown content, manage media, and handle theme-related tasks. To start, run the server in an environment where you can provide your WeChat credentials. The client then sends requests to the server to perform actions such as publishing articles, uploading media, or previewing themes.

To configure your MCP client, use a stdio connection that launches the server process directly. You will provide the Python command and the path to the server entry script, along with required environment variables for WeChat API access.

How to install

Prerequisites you need before installation are Python 3.9 or newer and WeChat Official Account developer access. You will also use an MCP client that can start and communicate with a stdio-based server.

# Clone the project repository
git clone https://github.com/herofox/xiayan-mcp.git
cd xiayan-mcp

# Create and activate a virtual environment (recommended)
python -m venv venv
# Linux/macOS
source venv/bin/activate
# Windows
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Prepare environment variables (copy the example and fill in credentials)
cp .env.example .env
# Edit .env to include WECHAT_APP_ID and WECHAT_APP_SECRET

MCP configuration (stdio server)

Configure your MCP client to launch the 夏颜 MCP Server as a local stdio process. Use the Python interpreter to run the server script and supply the WeChat credentials via environment variables.

{
  "mcpServers": {
    "xiayan-mcp": {
      "name": "夏颜公众号助手",
      "command": "python",
      "args": ["path/to/xiayan-mcp/run.py"],
      "env": {
        "WECHAT_APP_ID": "your_wechat_app_id",
        "WECHAT_APP_SECRET": "your_wechat_app_secret"
      }
    }
  }
}

Environment variables and interactive configuration

During startup, the server checks whether YouChat credentials are set. If not, you will be interactively prompted to enter the WeChat App ID and App Secret. You can choose to save credentials to a .env file for automatic loading on future starts.

Manual environment variables you may set include WECHAT_APP_ID and WECHAT_APP_SECRET. You can also reconfigure credentials at any time using the credentials management tool.

Common command-line options include --reconfigure to force credential re-entry and --debug to enable verbose logs.

Credentials management

The server provides a dedicated credential management utility to securely view, update, and delete WeChat API credentials.

# View current credentials (sensitive parts hidden)
python credentials_manager.py view

# Update credentials
python credentials_manager.py update

# Delete credentials
python credentials_manager.py delete

Using the built-in MCP tools

夏颜 MCP Server exposes a collection of tools to publish content, manage themes, and handle media. You will use these tools through the MCP client to perform common publishing workflows.

Troubleshooting tips

If the server cannot start, verify that Python 3.9+ is installed, the WeChat App ID and App Secret are correct, and your environment variables are correctly loaded. Ensure the server process has network access if you are publishing to WeChat.

Available tools

publish_article

Publish a Markdown article to the WeChat draft box with a chosen theme and optional publishing options.

list_themes

Retrieve information about all available themes, including whether a custom template or CSS is used in detailed mode.

upload_temp_media

Upload a temporary media file to WeChat for up to 3 days.

upload_permanent_material

Upload a permanent material item to WeChat with an optional description for videos.

upload_image_for_news

Upload an image specifically for rich-text/news content and receive a usable URL.

get_media_list

Fetch a list of media materials from WeChat with pagination options.

delete_permanent_material

Delete a specified permanent material by its media_id.

preview_theme

Get an HTML preview of a specified theme for verification before publishing.

add_custom_theme

Add a new custom theme with a unique ID, name, and description.

update_theme

Update properties of an existing theme, such as name, description, or templates.