mcp-zhipu-text-to-image-kuma

v1.0.0

Published

5 months ago

MCP server for text-to-image generation using Zhipu AI CogView-4 API

0High
0Medium
0Low

kuma_wan

mcp model-context-protocol text-to-image image-generation zhipu cogview ai

文生图 MCP 服务器

基于 FastMCP 框架实现的文本生成图片 MCP 服务器，集成智谱 API (CogView-4)。

特性

✅ 基于 MCP (Model Context Protocol) 标准协议
✅ 集成智谱 CogView-4 图片生成 API
✅ 支持 stdio 传输模式（标准 MCP 模式）
✅ 完整的日志记录和错误处理
✅ 支持 Claude Desktop、Cline 等 MCP 客户端
✅ 可通过 NPM 安装和使用

快速开始

方式一：通过 NPM 安装（推荐）

npm install -g mcp-zhipu-text-to-image-kuma

方式二：从源码安装

git clone https://github.com/2716025420/mcp-zhipu-text-to-image-kuma.git
cd mcp-zhipu-text-to-image-kuma
pip install -r requirements.txt

环境要求

Python 3.8 或更高版本
智谱 API Key（从智谱 AI 开放平台获取）

配置

1. 获取 API Key

访问智谱 AI 开放平台，注册并获取 API Key。

2. 配置环境变量

创建 .env 文件（或设置系统环境变量）：

ZHIPU_API_KEY=your_actual_api_key_here

使用方法

在 Claude Desktop 中使用

编辑 Claude Desktop 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "mcp-zhipu-text-to-image-kuma": {
      "command": "python",
      "args": ["F:\\mcp3\\varable_try_mcp.py"],
      "env": {
        "ZHIPU_API_KEY": "your_api_key_here"
      }
    }
  }
}

如果通过 NPM 安装，可以使用：

{
  "mcpServers": {
    "mcp-zhipu-text-to-image-kuma": {
      "command": "npx",
      "args": ["-y", "mcp-zhipu-text-to-image-kuma"],
      "env": {
        "ZHIPU_API_KEY": "your_api_key_here"
      }
    }
  }
}

重启 Claude Desktop，即可在对话中使用文生图功能。

在 Cline (VS Code) 中使用

打开 Cline 设置，添加 MCP 服务器配置：

{
  "mcpServers": {
    "mcp-zhipu-text-to-image-kuma": {
      "command": "python",
      "args": ["F:\\mcp3\\varable_try_mcp.py"],
      "env": {
        "ZHIPU_API_KEY": "your_api_key_here"
      }
    }
  }
}

直接运行

# 从源码运行
python varable_try_mcp.py

# 或通过 NPM 运行
npm start

工具说明

generate_image

根据提示词生成图片。

参数:

prompt (必需): 图片描述提示词，例如 "小猫在玩耍"
size (可选): 图片尺寸，默认 "1024x1024"
quality (可选): 图片质量，默认 "standard"

返回示例:

{
  "input_prompt": "小猫在玩耍",
  "output_urls": [
    "https://open.bigmodel.cn/image-output/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
  ],
  "created": 1735689600,
  "content_filter": [
    {
      "role": "assistant",
      "level": 1
    }
  ]
}

错误示例:

{
  "error": "API 错误: 无效的Authorization Token，请检查token是否正确或已过期",
  "error_code": "INVALID_AUTH_TOKEN",
  "input_prompt": "小猫在玩耍"
}

使用示例

在 Claude Desktop 中：

用户: 请使用文生图工具生成一张小猫在玩耍的图片

Claude: 好的，我来为您生成图片...
[调用 generate_image 工具]

生成成功！图片链接：
https://open.bigmodel.cn/image-output/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png

项目结构

mcp3/
├── varable_try_mcp.py    # MCP 服务器主程序
├── requirements.txt       # Python 依赖
├── package.json           # NPM 配置
├── run.js                 # NPM 启动脚本
├── .env                   # 环境变量配置 (API Key)
├── .gitignore             # Git 忽略文件
├── LICENSE                # MIT 许可证
└── README.md              # 项目说明文档

API 配置

模型: cogView-4-250304
API 端点: https://open.bigmodel.cn/api/paas/v4/images/generations
超时时间: 60 秒

日志输出

服务器运行时会输出详细的日志信息：

服务启动信息
API 调用请求
API 响应状态
错误信息

发布到 NPM

准备工作

发布步骤

更新 package.json 中的信息（名称、作者、仓库等）
确保所有文件都已提交到 Git
发布到 NPM：
```
npm publish
```

更新版本

# 补丁版本（bug 修复）
npm version patch

# 次要版本（新功能）
npm version minor

# 主要版本（破坏性更改）
npm version major

# 发布新版本
npm publish

故障排查

Claude Desktop 无法连接

检查配置文件路径是否正确
确保 Python 路径正确（使用绝对路径）
查看日志文件：
- Windows: %APPDATA%\Claude\logs\mcp*.log
- Mac: ~/Library/Logs/Claude/mcp*.log

API Key 无效

检查 .env 文件格式（无引号，无空格）
验证 API Key 是否过期
确认 API Key 有图片生成权限

请求超时

检查网络连接
验证智谱 API 服务状态
增加超时时间（修改代码中的 timeout 参数）

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 详见 LICENSE 文件

更新日志

v1.0.0 (2025-12-08)

🎉 首次发布
✅ 支持文本生成图片功能
✅ 集成智谱 CogView-4 API
✅ 支持 stdio 传输模式
✅ 完整的日志和错误处理

作者: Your Name
最后更新: 2025-12-08