Pushplus Mcp Server

pushplus mcp server

Model Context Protocol（MCP）に基づく pushplus プッシュサーバーです。AI アシスタントが pushplus を通じて、WeChat、メールなどのチャネルにプッシュメッセージを送信できます。

🎉 NPM で公開されました！
npm install -g @perk-net/pushplus-mcp-server で直接インストールして使用できます。ソースコードのダウンロードは不要です。

📋 目次

• 機能の特長
• 🚀 クイックスタート
• 📱 機能の使い方
• 🛠️ コマンドラインツール
• 📖 使用例
• 🔍 トラブルシューティング
• 👨‍💻 開発

機能の特長

• 🚀 MCP を完全サポート: Model Context Protocol 仕様を実装しています
• 📱 複数チャネルへのプッシュ: WeChat、QQ ボット、メール、SMS、企業版 WeChat など、さまざまなプッシュチャネルをサポートしています
• 🎨 複数のメッセージ形式: HTML、Markdown、プレーンテキスト、JSON などの形式をサポートしています
• 🔧 柔軟な設定: デプロイしやすい環境変数による設定をサポートしています
• 🛡️ 型安全: TypeScript で開発されており、完全な型サポートを提供します
• 📊 状態監視: サーバーの状態や設定情報を確認できます
• 🧪 テストしやすい設計: 設定テストとメッセージ送信テストを内蔵しています

🚀 クイックスタート

方法 1：NPM からインストール（推奨）

npm install -g @perk-net/pushplus-mcp-server

インストールが完了すると、pushplus-mcp コマンドをグローバルに使用できるようになります。

メリット：

• ✅ 簡単にインストールでき、1 つのコマンドで完了します
• ✅ 依存関係を自動的に処理します
• ✅ グローバルなコマンドラインツールとして使用できます
• ✅ ソースコードのダウンロードは不要です

方法 2：ソースコードからビルド

コードを変更したり、開発に参加したりする場合：

# 克隆项目
git clone https://github.com/pushplus/pushplus-MCP-Server-TypeScript.git
cd pushplus-MCP-Server-TypeScript

# 安装依赖
npm install

# 构建项目
npm run build

# 测试配置
npm run test

適した用途：

• 🛠️ カスタム機能が必要な場合
• 🔧 プロジェクト開発に参加する場合
• 📊 詳細なログをデバッグする必要がある場合

pushplus token の取得

1. pushplus 公式サイトにアクセスします
2. WeChat の QR コードをスキャンしてログインします
3. 個人センターで Token を取得します

設定のテスト

# 设置环境变量
export PUSHPLUS_TOKEN=your_pushplus_token_here

# 测试配置
pushplus-mcp --test

設定が正しければ、テスト用のプッシュメッセージが届きます！

Claude Desktop への統合

1. Claude Desktop の設定を開き、Developer → Edit Config を選択します
2. 設定を追加します（お使いの OS に応じて選択してください）：

NPM インストールの場合 - Windows：

{
  "mcpServers": {
    "pushplus": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@perk-net/pushplus-mcp-server"
      ],
      "env": {
        "PUSHPLUS_TOKEN": "您的Token",
        "PUSHPLUS_SECRET_KEY": "您的SecretKey"
      }
    }
  }
}

NPM インストールの場合 - Mac/Linux：

{
  "mcpServers": {
    "pushplus": {
      "command": "npx",
      "args": [
        "-y",
        "@perk-net/pushplus-mcp-server"
      ],
      "env": {
        "PUSHPLUS_TOKEN": "您的Token",
        "PUSHPLUS_SECRET_KEY": "您的SecretKey"
      }
    }
  }
}

ソースコードからビルドした場合：

{
  "mcpServers": {
    "pushplus": {
      "command": "node",
      "args": ["/path/to/pushplus-mcp-server/dist/index.js"],
      "env": {
        "PUSHPLUS_TOKEN": "您的Token",
        "PUSHPLUS_SECRET_KEY": "您的SecretKey"
      }
    }
  }
}

設定ファイルの場所：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Claude Desktop を再起動します

使い始めましょう！

Claude に次のように伝えます：

"请发送一条测试推送消息到我的微信"

🎉 おめでとうございます！pushplus mcp server の設定が完了しました！

📝 設定に関する説明：Claude Desktop の設定で env.PUSHPLUS_TOKEN を設定している場合、.env ファイルを作成する必要はありません。MCP サーバーは、Claude Desktop から渡される環境変数を自動的に読み込みます。

📱 機能の使い方

使用可能なツール

1. send_push_message - プッシュメッセージの送信

最新の /send インターフェースに対応した、すべての機能を備えたプッシュメッセージツールです：

{
  "content": "消息内容（必填）",
  "title": "消息标题（可选）",
  "icon": "消息图标（可选）",
  "template": "html",
  "channel": "wechat",
  "topic": "群组编码（可选）",
  "to": "好友令牌（可选）",
  "pre": "预处理编码（可选，仅供会员使用）",
  "webhook": "webhook编码（可选，非URL）",
  "option": "渠道配置参数（可选，与webhook等价）",
  "callbackUrl": "回调地址（可选）",
  "timestamp": "1632993318000",
  "pushId": "form/doc/excel/webdiff 模板必填"
}

2. send_text_message - テキストメッセージの送信

プレーンテキストメッセージをすばやく送信します：

{
  "content": "纯文本内容",
  "title": "消息标题（可选）",
  "topic": "群组编码（可选）",
  "to": "好友令牌（可选）",
  "pre": "预处理编码（可选）",
  "channel": "wechat"
}

3. send_html_message - HTML メッセージの送信

HTML 形式のメッセージを送信します：

{
  "content": "<h1>HTML内容</h1><p>支持HTML标签</p>",
  "title": "消息标题（可选）",
  "topic": "群组编码（可选）",
  "to": "好友令牌（可选）",
  "pre": "预处理编码（可选）",
  "channel": "wechat"
}

4. send_markdown_message - Markdown メッセージの送信

Markdown 形式のメッセージを送信します：

{
  "content": "# Markdown标题\n\n支持**粗体**和*斜体*",
  "title": "消息标题（可选）",
  "topic": "群组编码（可选）",
  "to": "好友令牌（可选）",
  "pre": "预处理编码（可选）",
  "channel": "wechat"
}

5. send_json_message - JSON メッセージの送信

JSON 形式のメッセージを送信します：

{
  "content": "{\"data\": \"JSON格式内容\"}",
  "title": "消息标题（可选）",
  "topic": "群组编码（可选）",
  "to": "好友令牌（可选）",
  "pre": "预处理编码（可选）",
  "channel": "wechat"
}

6. batch_send_message - 複数チャネルへの一括送信

/batchSend インターフェースに対応しており、複数のチャネルに同時に送信できます：

{
  "content": "消息内容",
  "channel": "wechat,mail,webhook",
  "option": ",,webhook编码",
  "title": "消息标题（可选）",
  "template": "html",
  "pushId": "form/doc/excel/webdiff 模板必填"
}

7. オープンインターフェースツール（open_*）

PUSHPLUS_TOKEN と PUSHPLUS_SECRET_KEY を設定すると使用できます。すべての /open/** インターフェースに対応しており、命名規則は open_<モジュール>_<アクション> です。PUSHPLUS_TOKEN には、メッセージ送信で使用するものと同じ token を指定します。

モジュール	ツールの例
auth	open_get_access_key
user	open_user_my_info / open_user_token / open_user_send_count
message	open_message_list / open_message_send_result / open_message_delete
token	open_token_list / open_token_add / open_token_edit / open_token_delete
topic	open_topic_list / open_topic_add / open_topic_detail など
topicUser	open_topic_user_subscriber_list / open_topic_user_add_blacklist など
friend	open_friend_list / open_friend_add_blacklist など
webhook	open_webhook_list / open_webhook_add など
setting	open_setting_list_user_default など
pre	open_pre_list / open_pre_test など
forwardRule	open_forward_rule_list / open_forward_rule_add / open_forward_rule_test / open_forward_rule_save_setting など
forwardLog	open_forward_log_list / open_forward_log_detail
channel	open_mail_list / open_mp_list / open_cp_list
clawBot	open_clawbot_bot_info / open_clawbot_get_msg など
cmcc	open_cmcc_bind / open_cmcc_info / open_cmcc_unbind / open_cmcc_test
qqBot	open_qqbot_my_bots / open_qqbot_get_bind_link / open_qqbot_bot_info / open_qqbot_set_default / open_qqbot_group_list / open_qqbot_list / open_qqbot_add / open_qqbot_custom_bot_preview / open_qqbot_custom_bot_add / open_qqbot_custom_bot_delete など（バインド系インターフェースでは、botAppId を指定して独自のボットを使用できます）
file/image	open_file_upload_image / open_user_image_list
pay	open_pay_transfer_order（高リスク）

説明：

• オープンインターフェースの実際の URL は https://www.pushplus.plus/api/open/... の形式です。送信インターフェースは引き続き /send です
• MCP は access-key を自動的に取得してキャッシュします（約 60 秒前に更新）
• PUSHPLUS_TOKEN にはユーザー tokenを指定する必要があります（オープンインターフェースはメッセージ token をサポートしていません）
• 使用前に公式サイトでオープンインターフェースを有効にし、安全 IP を設定する必要があります
• 各 open_* ツールのリクエスト／レスポンスフィールドの説明は、公式ドキュメントに準拠しています：https://www.pushplus.plus/doc/guide/openApi.html
• 削除／出金／バインド解除などのツールは、description に「高リスク」と記載されています

可用资源

1. pushplus://status - 服务器状态

获取服务器运行状态和配置信息

2. pushplus://templates - 支持的模板

获取所有支持的消息模板类型

3. pushplus://channels - 支持的渠道

获取所有支持的推送渠道信息

支持的消息模板

模板类型	描述	备注
html	HTML格式消息	默认模板
txt	纯文本消息
json	JSON格式消息
markdown	Markdown格式消息
cloudMonitor	阿里云监控报警定制模板
jenkins	Jenkins插件定制模板
route	路由器插件定制模板
pay	支付成功通知模板
order	订单支付成功模板
verify	实名认证模板
form	表单格式模板	需传 pushId
doc	文档格式模板	需传 pushId
excel	表格格式模板	需传 pushId
webdiff	网页差异对比模板	需传 pushId

支持的推送渠道

渠道类型	描述	备注
wechat	微信公众号推送	默认渠道
webhook	第三方webhook推送	传 webhook/option 编码（非URL）
cp	企业微信应用推送	需要配置企业微信应用
mail	邮箱推送	需要绑定邮箱
sms	短信推送	需要绑定手机号
voice	语音推送	需要绑定手机号
extension	浏览器插件推送
app	App推送	需要先登录App
clawbot	微信ClawBot推送	需要配置ClawBot
cmcc	新消息ClawBot推送	仅支持中国移动；需先绑定 Channel API Key；不填 option
qq	QQ机器人推送	需先绑定（支持官方机器人和自有机器人）；不填 option 由默认机器人发给自己，填配置编码发到对应QQ群或用指定机器人发给自己

🛠️ 命令行工具

NPM 安装用户

# 显示帮助信息
pushplus-mcp --help

# 显示版本信息
pushplus-mcp --version

# 测试配置（包含发送测试消息）
pushplus-mcp --test

# 显示当前配置
pushplus-mcp --config

# 启动服务器（默认命令）
pushplus-mcp

源码构建用户

# 显示帮助信息
node dist/index.js --help

# 显示版本信息
node dist/index.js --version

# 测试配置（包含发送测试消息）
npm run test

# 显示当前配置
node dist/index.js --config

# 启动服务器（默认命令）
npm start

# 开发模式
npm run dev

# 监听模式构建
npm run watch

环境变量

变量名	描述	默认值	必需
PUSHPLUS_TOKEN	用户 Token（发送与开放接口共用）	-	✅
PUSHPLUS_SECRET_KEY	开放接口 secretKey	-	调用 open_* 时需要
PUSHPLUS_BASE_URL	API 根地址	https://www.pushplus.plus	❌
PUSHPLUS_OPEN_API_PREFIX	开放接口前缀（发送不走此前缀）	/api	❌
MCP_SERVER_NAME	MCP 服务器名称	pushplus-mcp-server	❌
MCP_SERVER_VERSION	MCP 服务器版本	1.1.0	❌
DEFAULT_TEMPLATE	默认消息模板	html	❌
DEFAULT_CHANNEL	默认推送渠道	wechat	❌
DEBUG	调试模式	false	❌

📖 使用示例

1. 基本文本推送

在 Claude 中询问：

请使用 pushplus 发送一条测试消息，标题是"测试消息"，内容是"这是一条来自 Claude 的测试消息"

Claude 会调用 send_text_message 工具发送纯文本消息。

2. HTML 格式推送

请发送一条 HTML 格式的消息，标题"系统通知"，内容包含：
- 一个标题
- 一个列表
- 一些样式

Claude 会调用 send_html_message 工具发送带样式的消息。

3. Markdown 格式推送

请发送一条 Markdown 格式的消息，包含代码块和表格

Claude 会调用 send_markdown_message 工具发送 Markdown 格式的消息。

4. JSON 格式推送

请发送一条 JSON 格式的消息，标题"API响应"，内容为用户数据的JSON格式

Claude 会调用 send_json_message 工具发送 JSON 格式的消息，适合发送结构化数据。

5. 自定义参数推送

请使用完整参数发送推送消息：
- 标题：重要通知
- 内容：HTML 格式的内容
- 推送渠道：微信
- 群组：开发团队
- 好友令牌：指定接收人

Claude 会调用 send_push_message 工具，使用所有可用参数。

6. 好友推送

请发送消息给特定好友，使用好友令牌：token1,token2

使用 to 参数可以指定具体的接收人，支持多人推送（逗号分隔）。

7. 理解响应结果

⚠️ 重要说明：HTTP 请求成功（状态码 200）并不代表消息发送成功，只是表示请求已被服务器接收处理。

响应结果解释

当您发送消息后，会收到如下格式的响应：

{
  "code": 200,
  "msg": "请求成功",
  "data": "abc123def456"
}

字段说明：

• code: HTTP 响应状态码
  • 200: 请求成功被服务器接收
  • 其他值: 请求失败，需检查参数或配置
• msg: 服务器返回的消息说明
• data: 📋 流水号（重要！）- 这是消息的唯一标识符，可用于后续查询消息发送状态
• count: 消息发送数量

📌 注意事项：

• 收到 code: 200 只表示服务器接受了推送请求
• 实际的消息发送可能需要一些时间完成
• 如需确认消息是否真正送达，请保存返回的 data（流水号）用于后续状态查询

8. 查询服务器状态

询问 Claude：

请查看 pushplus mcp server 的状态信息

Claude 会读取 pushplus://status 资源，显示服务器状态。

9. 查看支持的功能

询问 Claude：

pushplus 支持哪些消息模板？

Claude 会读取 pushplus://templates 资源，显示所有支持的模板类型。

询问 Claude：

pushplus 支持哪些推送渠道？

Claude 会读取 pushplus://channels 资源，显示所有支持的推送渠道。

🔍 故障排除

常见问题

1. Token 无效

❌ 配置验证失败: PUSHPLUS_TOKEN 格式不正确，应为32位字符串

解决方案:

• 检查您的 pushplus token 是否正确，Token 应该是32位的字母数字组合
• 确认 Token 是否有效且有足够的推送额度

2. 推送失败

❌ 发送失败: HTTP请求失败: 400 Bad Request

解决方案:

• 检查消息内容是否符合格式要求
• 确认 Token 有效且有足够的推送额度
• 检查网络连接
• 确认消息标题不超过100字符

3. 理解响应状态

✅ HTTP请求成功
📊 响应详情:
- 状态码: 200
- 消息: 请求成功
- 📋 流水号: abc123def456 （重要！可用于查询消息发送状态）
- 计数: 1
⚠️ 注意：HTTP请求成功不代表消息已送达，实际发送可能需要一些时间。

说明:

• 状态码 200 表示服务器成功接收了推送请求
• 流水号 是消息的唯一标识符，请妥善保存用于后续查询
• 消息实际送达可能需要几秒到几分钟的时间
• 如需确认消息是否真正送达，可使用流水号查询消息状态

4. 配置文件问题

❌ 配置验证失败: 缺少 PUSHPLUS_TOKEN 环境变量

解决方案:

• 确保 .env 文件存在并包含正确的配置
• 或者通过环境变量直接设置 PUSHPLUS_TOKEN（如 Claude Desktop 配置）
• 检查环境变量是否正确传递到 MCP 服务器

5. MCP 连接失败

解决方案:

• 确认 Claude Desktop 配置正确
• 检查命令和参数是否正确
• 重启 Claude Desktop
• 确认 NPM 包已正确安装

6. NPM 包无法找到

解决方案:

# 重新安装
npm uninstall -g @perk-net/pushplus-mcp-server
npm install -g @perk-net/pushplus-mcp-server

# 验证安装
pushplus-mcp --version

👨‍💻 开发

项目结构

pushplus-mcp-server/
├── src/
│   ├── index.ts          # 程序入口
│   ├── server.ts         # MCP 服务器实现
│   ├── pushplus.ts       # pushplus API 客户端
│   └── config.ts         # 配置管理
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 项目文档

开发脚本

# 构建项目
npm run build

# 监听模式构建
npm run watch

# 清理构建文件
npm run clean

# 重新构建
npm run rebuild

# 开发模式（构建并启动）
npm run dev

TypeScript 支持

项目使用 TypeScript 开发，提供完整的类型支持：

• 严格类型检查: 启用 TypeScript 严格模式
• Zod 验证: 使用 Zod 进行运行时类型验证
• 完整类型定义: 所有 API 和配置都有完整的类型定义

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

MIT License - 详见 LICENSE 文件

相关链接

• pushplus 官网
• Model Context Protocol
• MCP TypeScript SDK
• Claude Desktop

---