wecom-mail-mcp

# WeCom Mail MCP A Python-based MCP server that sends regular emails using the official WeCom email API. It does a simple thing: - Exposes `send_email` to AI - Sends emails through the official WeCom interface - Reads `CORPID` / `CORPSECRET` from environment variables or `.env` - Compatible with `uv run` and `uvx --from ...` ## Features - Official WeCom email API sending, not through SMTP - Automatically obtains and caches `access_token` - Compatible with `text` / `html`, also compatible with `text/plain` / `text/html` - Provides `get_mailbox_info` to easily confirm the current sender's email - Supports `stdio`, `sse`, and `streamable-http` transport methods ## Prerequisites Confirm the following on the WeCom side: 1. Have a usable `CORPID` 2. Have a corresponding app `CORPSECRET` 3. The app has "email" permissions 4. The app's email account is configured 5. The app secret used to call the email interface is within the "callable apps" range Official documentation: - Get access_token: <https://developer.work.weixin.qq.com/document/path/91039> - Send regular emails: <https://developer.work.weixin.qq.com/document/path/97445> - Query app email accounts: <https://developer.work.weixin.qq.com/document/path/97991> ## Environment Variables / `.env` The server will automatically load the `.env` file in the project root directory. The priority is: command line coverage > `.env` > system environment variables. That is, if `.env` is written, it will be used as `.env`; if `.env` is not written or left blank, it will fall back to system environment variables. Required: - `WECOM_CORP_ID` - `WECOM_CORP_SECRET` Compatible aliases: - `CORPID` - `CORPSECRET` Optional: - `WECOM_API_BASE`, default `https://qyapi.weixin.qq.com` - `WECOM_REQUEST_TIMEOUT`, default `20` - `WECOM_MCP_TRANSPORT`, default `stdio` - `WECOM_MCP_HOST`, default `127.0.0.1` - `WECOM_MCP_PORT`, default `8000` - `WECOM_LOG_LEVEL`, default `INFO` ## Local Run ### 1. Install dependencies ```bash uv sync ``` ### 2. Configure `.env` The project provides a `.env.example` and a local `.env` template. The easiest way is to directly edit the root directory `.env`: ```env CORPID=your_corpid CORPSECRET=your_corpsecret ``` If you don't want to use `.env`, you can also use system environment variables. ### 3. Set environment variables PowerShell: ```powershell $env:CORPID="your_corpid" $env:CORPSECRET="your_corpsecret" ``` ### 4. Verify configuration ```bash uv run wecom-mail-mcp --check-config ``` Successful output will display the current app email account and alias email list. ### 5. Start MCP with stdio ```bash uv run wecom-mail-mcp ``` ## Can `uvx` work? Yes. For Python projects, `uvx` is similar to `npx` in the Node ecosystem. This project provides a console script, so you can run it directly in the local directory: ```bash uvx --from . wecom-mail-mcp ``` If you publish it to PyPI later, you can directly run: ```bash uvx wecom-mail-mcp ``` ## Claude Desktop configuration example ```json { "mcpServers": { "wecom-mail": { "command": "uvx", "args": [ "--from", "d:/Code_Save/Py/send_email_mcp", "wecom-mail-mcp" ], "env": { "CORPID": "your_corpid", "CORPSECRET": "your_corpsecret" } } } } ``` If you prefer `uv run`, you can also: ```json { "mcpServers": { "wecom-mail": { "command": "uv", "args": [ "run", "--directory", "d:/Code_Save/Py/send_email_mcp", "wecom-mail-mcp" ], "env": { "CORPID": "your_corpid", "CORPSECRET": "your_corpsecret" } } } } ``` ## MCP Tools ### `send_email` Parameters: - `to_email`: recipient's email - `subject`: email subject - `content`: email content - `content_type`: optional, supports `text`, `html`, `text/plain`, `text/html`, default `text` Description: - The sender is not passed by AI, but by the WeCom "app email account" - The server will map `text/plain` to the official interface's `text` - The server will map `text/html` to the official interface's `html` - If sending HTML, please explicitly pass `content_type="html"` - The MCP tool description will directly inform the client of HTML email compatibility limitations to avoid sending webpage templates directly as email templates ### HTML Email Compatibility Suggestions If you want to send HTML emails, follow the most conservative email writing style: - Prioritize using `table`, `tbody`, `tr`, `td` for layout - Use `p`, `br`, `span`, `strong`, `b`, `em`, `i`, `h1` to `h4`, `a`, `img` for text and basic content - Write styles as inline styles, avoid complex selectors - Use public `https` absolute addresses for images Avoid: - `script`, `iframe`, `form`, `video`, `audio`, `canvas`, `svg` - External CSS, Web Font - `flex`, `grid`, `position` - Relative paths, local paths, complex webpage templates Recommended skeleton: ```html <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"> <tr> <td> <h2 style="margin:0 0 16px;">Title</h2> <p style="margin:0 0 12px;">Content</p> <a href="https://example.com">Link</a> <img src="https://example.com/demo.png" alt="" style="display:block;width:100%;height:auto;border:0;" > </td> </tr> </table> ``` ### `get_mailbox_info` Returns the current app email account and alias email list to easily confirm the sender's identity. ## HTTP Mode If you want to use HTTP transport: ```bash uv run wecom-mail-mcp --transport streamable-http --host 127.0.0.1 --port 8000 ``` ## Development Test ```bash python -m unittest discover -s tests ```