手把手教你用 WorkBuddy 接入腾讯混元大模型，实现 AI 对话与生图

混元MCP接入教程.md

前言

WorkBuddy 是腾讯推出的全场景 AI 办公工作台，不仅能对话，还能实际执行任务、操作文件。但你知道吗？通过 MCP（模型上下文协议），WorkBuddy 还可以接入腾讯自家的混元大模型，实现文本对话和 AI 生图能力。

本文记录了我真实操作的全过程，从零开始搭建混元 MCP Server，配置到 WorkBuddy 中，最终成功调用混元模型进行对话和生图。全程实操，踩过的坑都记录下来了，照着做就能复现。

一、准备工作

1.1 需要什么

1.2 获取 TokenHub API Key

混元大模型通过腾讯云 TokenHub 提供 OpenAI 兼容接口，需要创建一个专门的 API Key。

步骤：

1. 登录腾讯云控制台，访问 TokenHub 控制台：https://console.cloud.tencent.com/tokenhub/
2. 开通 TokenHub 服务
3. 进入 API Key 管理页面，点击「创建 API Key」
4. 填写 Key 名称（如"WorkBuddy-Hunyuan"），访问范围选「全选」
5. 点击确定，立即复制保存 API Key（格式类似 sk-xxxxxxxx，只显示一次！）

注意：TokenHub API Key 和腾讯云 CAM 的 SecretId/SecretKey 是两种不同的鉴权方式。混元 OpenAI 兼容接口需要的是 TokenHub API Key，不是 CAM 密钥。

二、搭建混元 MCP Server

2.1 创建 Python 环境

首先创建一个隔离的 Python 虚拟环境并安装依赖：

2.2 编写 MCP Server 脚本

创建一个 server.py 文件，实现两个工具：hunyuan_chat（文本对话）和 hunyuan_image（生图）。

核心逻辑如下：

• 使用 MCP 2.0 协议，通过 @server.call_tool() 和 @server.list_tools() 注册工具
• 文本对话调用混元 OpenAI 兼容接口：https://tokenhub.tencentmaas.com/v1/chat/completions，模型使用 hy3
• 生图调用：https://tokenhub.tencentmaas.com/v1/images/generations，模型使用 hy-image-v3.0
• 生图结果自动下载到本地目录

完整代码已开源，文末附获取方式。

2.3 验证脚本

写完后先验证脚本能正常加载：

看到输出 Tools: ['hunyuan_chat', 'hunyuan_image'] 就说明没问题。

三、配置 WorkBuddy MCP 连接器

3.1 编辑 mcp.json

找到 WorkBuddy 的 MCP 配置文件，路径为：

注意：是 mcp.json，不是 .mcp.json。WorkBuddy 的「自定义连接器」读取的是不带点前缀的文件。

添加混元 MCP Server 配置：

3.2 信任连接器

1. 在 WorkBuddy 界面打开「连接器管理」→「自定义连接器」
2. 找到新出现的 hunyuan 连接器
3. 点击「信任」按钮启用

这一步是安全机制，必须在应用界面手动点击，无法通过代码绕过。

四、实测效果

4.1 文本对话测试

配置完成后，我直接对 WorkBuddy 说："用混元帮我打个招呼"。

WorkBuddy 自动调用 hunyuan_chat 工具，混元回复：

"我是混元，是由腾讯开发的大模型，专注于基础信息处理与逻辑响应。"

Token 消耗：prompt=21, completion=18, total=39 tokens。按 hy3 定价（输入1元/百万tokens，输出4元/百万tokens），这一次对话花费约 0.0001 元，几乎可以忽略。

4.2 生图测试

生图测试时遇到了混元平台 504 网关超时（平台侧临时问题），这是正常的，重试即可。混元生图首次开通赠送 50 次免费额度，足够测试使用。

五、混元模型定价参考

对比其他主流模型，混元 hy3 的定价非常有竞争力，尤其适合日常高频使用场景。

六、踩坑记录

坑1：SecretId vs TokenHub API Key

最初以为混元 API 用的是腾讯云 CAM 的 SecretId/SecretKey，折腾了好几轮才发现混元 OpenAI 兼容接口需要的是 TokenHub API Key。两者完全不同：

• CAM 密钥：AKID... 格式，用于腾讯云 SDK
• TokenHub API Key：sk-... 格式，用于混元 OpenAI 兼容接口

坑2：mcp.json vs .mcp.json

WorkBuddy 的「自定义连接器」读取的是 mcp.json（不带点前缀）。如果配置写到了 .mcp.json，连接器列表会显示为空。

坑3：MCP 2.0 API 变更

MCP 2.0 的 Python SDK API 有变化，不能用旧版装饰器。需要用 @server.call_tool() 和 @server.list_tools() 注册处理器，返回 types.CallToolResult 和 types.ListToolsResult。

七、总结

通过 MCP 协议接入混元大模型，WorkBuddy 的能力得到了进一步扩展：

1. 文本对话：hy3 模型中文能力强，适合日常问答、写作、翻译
2. AI 生图：混元生图擅长中国元素、东方美学风格
3. 成本极低：对话费用几乎可以忽略，生图有50次免费额度
4. 本地运行：MCP Server 跑在本地，数据不出机器

整个过程不需要高深的技术背景，跟着教程一步步操作即可完成。如果你也用 WorkBuddy，强烈推荐试试接入混元，体验腾讯自家大模型的能力。

本文为原创实操教程，基于真实操作记录。如有问题欢迎在评论区交流。