MCP Server¶

WeiLink provides an optional MCP (Model Context Protocol) server that exposes bot capabilities as tools for AI agents.

Install¶

pip install weilink[mcp]

This installs toolregistry-server with MCP support alongside the core package.

pip install weilink[server]

Run¶

WeiLink MCP server supports three transports: stdio (default), SSE, and streamable-http.

stdio (default)¶

# Via unified CLI
weilink mcp

# Or via Python module
python -m weilink.server

stdio transport is launched by an MCP client (Claude Desktop, Cursor, etc.) rather than run standalone.

SSE / HTTP¶

# SSE transport
weilink mcp -t sse -p 8000

# Streamable HTTP transport (recommended for network access)
weilink mcp -t http -p 8000

# With admin panel in the same process
weilink mcp -t http -p 8000 --admin-port 8080

# Bind to all interfaces
weilink mcp -t http --host 0.0.0.0 -p 8000

CLI Options¶

Client Configuration¶

Claude Desktop¶

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "weilink": {
      "command": "weilink",
      "args": ["mcp"]
    }
  }
}

Claude Code (stdio)¶

claude mcp add weilink -- weilink mcp

Claude Code (HTTP)¶

First start the MCP server:

weilink mcp -t http -p 8000

Then add it to Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "weilink": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Cursor / VS Code¶

Add to MCP settings:

{
  "mcpServers": {
    "weilink": {
      "command": "python",
      "args": ["-m", "weilink.server"]
    }
  }
}

Available Tools¶

recv¶

Poll for new messages from WeChat users.

Returns a JSON array of messages. Each message includes message_id, from_user, msg_type, text, timestamp, bot_id, and media metadata if applicable.

send¶

Send text and/or media to a WeChat user.

download¶

Download media from a previously received message.

Returns the saved file path and size.

history¶

Query message history from the persistent store.

Returns JSON with messages array, total count, limit, and offset.

sessions¶

List all sessions with their connection status. No parameters.

login¶

QR code login with built-in polling. The tool is stateful — its behavior depends on whether a login flow is already in progress:

Typical agent workflow:

1. Call login() — returns {"status": "pending", "qr_url": "..."}. Show the QR URL to the user.
2. Call login() again — polls for up to 30s, returns {"status": "scanned"} or {"status": "confirmed", ...}.
3. If still pending, call login() once more until confirmed or expired.

logout¶

Log out a session and remove its persisted credentials.

rename_session¶

Rename a session.

set_default¶

Set a session as the default.

Architecture¶

graph LR
    A[AI Agent] -->|MCP protocol| B[WeiLink MCP]
    B -->|WeiLink SDK| C[iLink API]
    C --> D[WeChat]

The MCP server wraps a WeiLink instance internally. Messages received via recv are cached (up to 1000) so their media can be downloaded later via download.

Skills Metadata¶

WeiLink ships two metadata files for registry discovery:

• server.json — Official MCP standard, used by MCP registries and package managers.
• smithery.yaml — Smithery registry format for auto-configuration.