Metadata-Version: 2.4
Name: qq-mcp
Version: 0.1.1
Summary: MCP server for sending messages to QQ groups via HTTP API
Author-email: Your Name <you@example.com>
License: MIT
Project-URL: Homepage, https://github.com/username/qq-mcp
Project-URL: Repository, https://github.com/username/qq-mcp
Keywords: mcp,qq,messaging,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27

# QQ MCP Server

[![PyPI version](https://img.shields.io/pypi/v/qq-mcp)](https://pypi.org/project/qq-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/qq-mcp)](https://pypi.org/project/qq-mcp/)

通过 HTTP API 向 QQ 群发送消息的 [MCP](https://modelcontextprotocol.io/) 服务端。基于 [python-sdk](https://github.com/modelcontextprotocol/python-sdk) 构建。

## 安装

```bash
pip install qq-mcp
```

## 配置

两种方式任选其一，优先级：**环境变量 > config.json**

### 方式一：config.json（推荐）

在当前工作目录创建 `config.json`：

```json
{
  "qq_api_url": "http://your-api:3000",
  "qq_token": "your-bearer-token",
  "qq_group_id": "123456789",
  "message_type": "text"
}
```

### 方式二：环境变量

```bash
export QQ_API_URL="http://your-api:3000"
export QQ_TOKEN="your-bearer-token"
export QQ_GROUP_ID="123456789"
export QQ_MESSAGE_TYPE="text"      # 可选，默认 text
```

## 使用

### Claude Code

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "qq-mcp": {
      "command": "qq-mcp"
    }
  }
}
```

### 命令行

```bash
qq-mcp                        # stdio 模式（默认）
qq-mcp --transport sse        # SSE HTTP 模式
python -m qq_mcp              # 模块方式启动
```

### 手动调用

```python
from qq_mcp import mcp

mcp.run()        # stdio
mcp.run("sse")   # SSE
```

## 工具

### send_qq_message

向 QQ 群发送消息。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `message` | `str` | 是 | 消息内容 |
| `group_id` | `str` | 否 | 覆盖默认群号 |
| `message_type` | `str` | 否 | 覆盖消息类型 |
| `api_url` | `str` | 否 | 覆盖 API 地址 |
| `token` | `str` | 否 | 覆盖 Bearer token |

示例：

```
send_qq_message(message="Hello, QQ!")
send_qq_message(message="Hi", group_id="987654321")
```

### hello

返回问候语。

```
hello(name="world")    # → "Hello, world!"
```

### add

两数相加。

```
add(a=1, b=2)          # → 3.0
```

## API 规范

服务端对接的 QQ API 接口：

```
POST {qq_api_url}/send_msg
Content-Type: application/json
Authorization: Bearer {qq_token}

{
  "message_type": "text",
  "group_id": "123456789",
  "message": "消息内容"
}
```

## License

MIT
