Content
# Tool List
Pure Python implementation of Tencent QQ Mail MCP Server. Based on reverse analysis of `@tencent-qqmail/agently-cli` v1.0.6 REST API protocol, **no Node.js/npm required**.
## Overview
This service is a **MCP (Model Context Protocol) Server**, implemented using **Python FastMCP** framework, which directly calls Tencent Agent REST API to complete mail operations through HTTP.
**Core Features:**
- Pure Python, zero Node.js dependency
- OAuth 2.0 Device Flow authentication (RFC 8628)
- Token local file persistence (`~/.config/agently-mail/token.json`)
- Supports two-stage confirmation for sending (to prevent misoperation)
- Automatic refresh of access_token
## Prerequisites
| Dependency | Version Requirement | Description |
|------|---------|------|
| Python | >= 3.10 | |
| `mcp` | >= 1.28 | MCP SDK |
| `httpx` | >= 0.27 | HTTP client |
## Installation
```bash
cd H:\agentmail-qq-cli
# Install Python dependencies
python -m pip install mcp httpx
```
## Configure in OpenCode
Edit `~/.config/opencode/opencode.json`, add:
```json
{
"mcp": {
"agently-mail": {
"type": "local",
"command": ["python", "H:\\agentmail-qq-cli\\agently_mcp_server.py"],
"enabled": true
}
}
}
```
Restart OpenCode to use.
## First Use: Login Authentication
Call `auth_login` tool in AI conversation:
```
auth_login()
```
Follow the prompts to complete authorization in the browser, and credentials will be saved in `~/.config/agently-mail/token.json`.
You can also specify the token directly through environment variables (skip OAuth):
```
set AGENTLY_ACCESS_TOKEN=your_token_here
```
## Available Tools (14)
### Mail Operations
| Tool | Description | Key Parameters |
|------|------|---------|
| `send_email` | Send new email (two-stage confirmation) | `to[]`, `subject`, `body`, `cc[]`, `bcc[]`, `attachment_ids[]` |
| `list_messages` | List emails | `limit`, `folder`(inbox/sent/trash/spam), `cursor`, `is_unread` |
| `read_message` | Read full content of email | `message_id` |
| `search_messages` | Search emails | `query`, `folder`, `limit`, `search_in` |
| `reply_message` | Reply to email (two-stage confirmation) | `message_id`, `body`, `reply_all` |
| `forward_message` | Forward email (two-stage confirmation) | `message_id`, `to[]`, `body` |
| `trash_message` | Move to trash (two-stage confirmation) | `message_id` |
### Attachment Operations
| Tool | Description | Key Parameters |
|------|------|---------|
| `upload_attachment` | Upload file as attachment | `file_path` |
| `download_attachment` | Download attachment to local | `message_id`, `attachment_id`, `output_dir` |
### Authentication and Account
| Tool | Description |
|------|------|
| `auth_login` | OAuth device flow login |
| `auth_status` | View authentication status |
| `auth_logout` | Logout and clear credentials |
| `auth_refresh` | Manually refresh access token |
| `get_user_info` | Get user information and alias list |
## Usage Examples
```
# View authentication status
auth_status()
# View current mailbox information
get_user_info()
# Inbox list
list_messages(limit=10, folder="inbox")
# Send email (two-stage confirmation)
send_email(
to=["colleague@example.com"],
subject="Quarterly Report",
body="Please check the quarterly report in the attachment.",
attachment_ids=["file_xxx"]
)
# First return confirmation_token, bring it to complete sending:
send_email(
to=["colleague@example.com"],
subject="Quarterly Report",
body="Please check the quarterly report in the attachment.",
attachment_ids=["file_xxx"],
confirmation_token="<token returned in the previous step>"
)
# Search emails
search_messages(query="meeting", folder="inbox", limit=20)
```
## Protocol Description
This service **does not** use traditional SMTP/IMAP/POP3 protocols, but implements email sending and receiving through **Tencent Agent REST API**.
| Function | Traditional Protocol | API Used |
|------|---------|-----------------|
| Sending | SMTP (25/465/587) | `POST /v1/aliases/{id}/messages/send` |
| Receiving | IMAP (143/993) / POP3 (110/995) | `GET /v1/aliases/{id}/messages` |
| Authentication | SMTP AUTH / SASL | OAuth 2.0 Device Flow |
| Attachment | MIME encoding | REST multipart upload/download |
| Token | None | Bearer JWT + refresh_token |
**API Endpoints:**
- Auth: `https://auth.agent.qq.com`
- REST: `https://api.agent.qq.com`
## Environment Variables
| Variable | Purpose |
|------|------|
| `AGENTLY_ACCESS_TOKEN` | Directly specify access_token, skip OAuth process |
| `AGENTLY_CLIENT_ID` | OAuth client_id (default `agently-cli`) |
| `AGENTLY_CLIENT_SECRET` | OAuth client_secret (optional) |
| `AGENTLY_CONFIG_DIR` | Configuration file directory (default `~/.config/agently-mail`) |
## Project Structure
```
H:\agentmail-qq-cli\
├── agently_mcp_server.py # MCP Server main program (pure Python, ~400 lines)
├── README.md # This file
└── LICENSE # MIT License
```
**Zero Node.js/npm dependencies.** Only one Python file and one JSON token file.
## License
MIT License
Copyright (c) 2026
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
