mingdao-collab-mcp

MCP Server for Mingdao Collaboration-era v1 API.

注意： 本项目封装的是明道协作时代的 v1 API，非明道云（HAP）零代码平台接口。这些接口在明道转型零代码后仍部分可用，主要覆盖动态、日程、私信、群组、通讯录等协作功能。

工具列表

默认启用约 44 个常用工具，非常用工具已注释，可按需启用（见下文）。

动态（post） — 9 个启用

已注释（不常用）：post_like、post_collect、post_top、post_vote、post_get_reply_by_me_posts、post_get_category_posts、post_get_common_categories

日程（calendar） — 8 个启用

已注释（不常用）：calendar_get_categories、calendar_get_subscription_url、calendar_create_category、calendar_confirm_invitation、calendar_reject_invitation、calendar_reinvite_member、calendar_remove_member、calendar_edit_category、calendar_edit_share、calendar_edit_private、calendar_edit_category_props、calendar_edit_reminder、calendar_remove_category

私信（webchat） — 6 个启用

已注释：webchat_delete_history、webchat_set_push

收件箱（message） — 2 个启用

已注释：message_favorite

群组（group） — 10 个启用

已注释：group_get_mentioned、group_get_unaudited、group_exit、group_apply_join、group_chat_to_post、group_audit_member、group_remove_admin、group_remove_member

用户（user） — 6 个启用

已注释：user_get_address_recommend、user_get_new_friends、user_add_friend、user_add_mobile_address、user_remove_friend、user_shield_friend、user_update_friend_status

组织架构（company） — 3 个启用

已注释：company_get_worksite、company_get_by_code、company_join_by_code、company_join_by_id、company_refuse_invitation

个人账户（passport） — 4 个启用

已注释：passport_logout、passport_send_verify_code、passport_update_account、passport_update_detail、passport_update_password、passport_update_user_card、passport_add_scale

已完全禁用的模块

以下模块在 server.py 中整体注释，不会加载任何工具：

• task（任务）— 7 个工具

启用 / 注释工具

启用某个已注释的工具

打开对应的 src/mingdao_collab_mcp/tools_xxx.py，找到注释掉的函数，去掉注释符号 # 即可：

# 注释状态（未启用）：
# @mcp.tool()
# def post_like(post_id: str, is_like: bool = True) -> dict:
#     """点赞或取消点赞一条动态。"""
#     return api_post("/v1/post/update_like_or_cancel_like_post", post_id=post_id, is_like=is_like)

# 启用后：
@mcp.tool()
def post_like(post_id: str, is_like: bool = True) -> dict:
    """点赞或取消点赞一条动态。"""
    return api_post("/v1/post/update_like_or_cancel_like_post", post_id=post_id, is_like=is_like)

启用整个模块

如需启用 passport 或 task 模块，编辑 src/mingdao_collab_mcp/server.py：

# 找到这两行，去掉注释：
# from . import tools_passport
# from . import tools_task

# 以及：
# tools_passport.register(mcp)
# tools_task.register(mcp)

注释掉某个工具

反过来操作，在 @mcp.tool() 和函数定义前加 # 即可。

修改后需重启 Claude Code 使其生效。

快速开始

1. 克隆项目

git clone https://github.com/andyleimc-source/mdold.git
cd mdold

2. 安装依赖（用虚拟环境，避免污染系统 Python）

python3 -m venv .venv
.venv/bin/pip install -e .

3. 配置凭证

cp .env.example .env

编辑 .env，填入你在明道开放平台创建的应用凭证：

MINGDAO_APP_KEY=你的app_key
MINGDAO_APP_SECRET=你的app_secret
MINGDAO_REDIRECT_URI=http://localhost:8080/callback

在哪里获取？登录 https://open.mingdao.com ，创建一个应用，在应用设置中获取 app_key 和 app_secret。回调地址必须与应用中配置的完全一致（包括端口号）。

4. 首次授权

# 生成授权链接
PYTHONPATH=src .venv/bin/python3 -m mingdao_collab_mcp.server authorize-url

# 在浏览器中打开输出的链接，登录明道账号并授权
# 授权后浏览器会跳转到回调地址，从 URL 中复制 code 参数值

# 用 code 换取 token
PYTHONPATH=src .venv/bin/python3 -m mingdao_collab_mcp.server exchange-code 你拿到的code

Token 会保存在 .secrets.json 中（已在 .gitignore 中排除）。

5. 在 Claude Code 中使用

在项目目录下运行（将路径替换为你的实际目录，用 pwd 查看）：

claude mcp add mdold \
  --scope user \
  --transport stdio \
  -e MINGDAO_APP_KEY=你的app_key \
  -e MINGDAO_APP_SECRET=你的app_secret \
  -e MINGDAO_REDIRECT_URI=http://localhost:8080/callback \
  -e PYTHONPATH=/absolute/path/to/mdold/src \
  -- /absolute/path/to/mdold/.venv/bin/python3 -m mingdao_collab_mcp.server mingdao

重启 Claude Code，就可以直接用自然语言操作明道了：

• "帮我看看张三最近发了什么动态"
• "创建一个明天上午 10 点的日程，邀请李四"
• "给王五发一条消息说下午 3 点开会"
• "列出公司所有部门"
• "查一下全体群有哪些成员"

Token 生命周期

如果超过 14 天没有使用，两个 token 都会过期，需要重新走一次浏览器授权流程（步骤 4）。

安全提醒

• .env 和 .secrets.json 包含敏感凭证，绝不要提交到 git
• 这两个文件已在 .gitignore 中排除
• 如果你 fork 了本项目，请确认这些文件没有被提交

项目结构

mdold/
├── .env.example          # 环境变量模板
├── .gitignore            # 排除密钥文件
├── pyproject.toml        # 项目配置
├── README.md
├── REQUIREMENTS.md       # 需求文档
└── src/mingdao_collab_mcp/
    ├── __init__.py
    ├── server.py          # MCP Server 入口（控制哪些模块加载）
    ├── auth.py            # OAuth token 管理
    ├── api_client.py      # HTTP 请求封装
    ├── tools_post.py      # 动态（11 个工具，7 个已注释）
    ├── tools_calendar.py  # 日程（21 个工具，13 个已注释）
    ├── tools_webchat.py   # 私信（8 个工具，2 个已注释）
    ├── tools_message.py   # 收件箱（3 个工具，1 个已注释）
    ├── tools_group.py     # 群组（18 个工具，8 个已注释）
    ├── tools_user.py      # 用户（13 个工具，7 个已注释）
    ├── tools_company.py   # 组织（8 个工具，5 个已注释）
    ├── tools_passport.py  # 个人账户（11 个工具，7 个已注释）
    └── tools_task.py      # 任务（整个模块已注释）

API 文档

本项目基于明道开放平台的 v1 API：https://open.mingdao.com/document

完整的接口参考见 REQUIREMENTS.md。

License

MIT

关注我

雷码工坊笔记 — 微信扫码关注