piapi-mcp-server

piapi-mcp-server

一个用 TypeScript 实现的 Model Context Protocol（MCP）服务，可与 PiAPI 的 API 集成。PiAPI 让用户能够直接通过 Claude 或任何其他兼容 MCP 的应用，使用 Midjourney/Flux/Kling/LumaLabs/Udio/Chrip/Trellis 生成媒体内容。

功能（即将推出更多）

注意：视频生成等耗时工具可能会因 Claude 的超时限制而无法完成

• 基础图像工具包
• 基础视频工具包
• 根据文本/图像提示词生成 Flux 图像
• 根据文本/图像提示词生成 Hunyuan 视频
• 根据图像提示词生成 Skyreels 视频
• 根据文本/图像提示词生成 Wan 视频
• 根据视频生成 MMAudio 音乐
• TTS 零样本语音生成
• Midjourney 图像生成
  • imagine
  • 其他
• Kling 视频与特效生成
• Luma Dream Machine 视频生成
• Suno 音乐生成
• Suno 歌词生成
• Udio 音乐与歌词生成
• 根据图像生成 Trellis 3D 模型
• 在大模型中规划工作流

Claude Desktop 使用示例

前置条件

• Node.js 16.x 或更高版本
• npm 或 yarn
• PiAPI API 密钥（可在 piapi.ai 获取）

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 PiAPI MCP Server：

npx -y @smithery/cli install piapi-mcp-server --client claude

手动安装

1. 克隆仓库：

git clone https://github.com/apinetwork/piapi-mcp-server
cd piapi-mcp-server

2. 安装依赖：

npm install

3. 构建项目：

npm run build

构建完成后，将生成 dist/index.js 文件。随后，你可以在 Claude Desktop 和其他应用程序中配置此文件。有关详细配置说明，请参阅“使用”部分。

4. （可选）使用 MCP Inspector 测试服务：

首先，在项目根目录中创建一个 .env 文件，并填入你的 API 密钥：

PIAPI_API_KEY=your_api_key_here

然后运行以下命令以启动 MCP Inspector：

npm run inspect

运行命令后，MCP Inspector 将在 http://localhost:5173（默认端口：5173）上可用。在浏览器中打开此 URL 即可开始测试。Inspector 操作的默认超时时间为 10000ms（10 秒），这可能不足以完成图像生成任务。测试图像生成或其他耗时操作时，建议延长超时时间。你可以在 URL 中添加 timeout 参数来调整超时时间，例如：http://localhost:5173?timeout=60000（将超时时间设为 60 秒）

MCP Inspector 是一款强大的开发工具，可帮助你测试和调试 MCP 服务实现。主要功能包括：

• 交互式测试：通过 Web 界面直接测试服务功能
• 实时反馈：查看函数调用的即时结果以及发生的任何错误
• 请求/响应检查：查看请求和响应的详细信息
• 函数文档：浏览可用函数及其参数
• 自定义参数：设置自定义超时值和其他配置选项
• 历史记录：跟踪之前的函数调用及其结果

有关使用 MCP Inspector 及其功能的详细信息，请访问 MCP 官方文档。

使用

连接到 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "piapi": {
      "command": "node",
      "args": ["/absolute/path/to/piapi-mcp-server/dist/index.js"],
      "env": {
        "PIAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

更新配置文件后，你需要重启 Claude Desktop。重启后，你应该会在输入框右下角看到一个锤子图标。 如需了解更多详细信息，请访问 MCP 官方文档

连接到 Cursor

注意：以下指南基于 Cursor 0.47.5。不同版本中的功能和行为可能有所不同。

配置 MCP 服务：

1. 前往：File > Preferences > Cursor Settings，或使用快捷键 Ctrl+Shift+J
2. 在左侧面板中选择“MCP”选项卡
3. 点击右上角的“Add new global MCP server”按钮
4. 在打开的 mcp.json 文件中添加你的配置

{
  "mcpServers": {
    "piapi": {
      "command": "node",
      "args": ["/absolute/path/to/piapi-mcp-server/dist/index.js"],
      "env": {
        "PIAPI_API_KEY": "your_api_key_here"
      }
    }
  }
}

5. 配置完成后，你会在 MCP Servers 页面看到一个“piapi”条目
6. 点击该条目上的 Refresh 按钮，或重启 Cursor，以连接到 piapi 服务

测试 piapi 图像生成：

1. 在 Cursor Chat 中打开并选择“Agent mode”，或使用快捷键 Ctrl+I
2. 输入测试提示词，例如：“generate image of a dog”
3. piapi 服务将根据你的提示词生成图像

禁用 piapi 服务：

1. 前往 Cursor Settings 中的 MCP Servers 页面
2. 在服务列表中找到“piapi”条目
3. 点击“Enabled”切换按钮，将其切换为“Disabled”

让工具与 PiAPI 保持同步（同步任务）

src/index.ts 会为每项已提交的 PiAPI (model, task_type) 功能注册一个由契约支持的 MCP 工具。工具名称是确定性的： piapi_<model>_<task_type>（例如， piapi_qubico_flux1_schnell_txt2img），其输入架构根据已提交的目录生成。现有的手写便捷工具仍然可用；由契约支持的工具可确保随着 Manager 目录的变化，所暴露的工具集始终完整。

src/index.ts 中的旧版便捷工具仍然是手写的，但完整的、由契约支持的工具集是根据已提交的目录生成的。本仓库包含一个可重复运行的漂移检测器，用于将该目录基线与 PiAPI Manager 的版本化 API 契约进行比较。它会检测新增 API、已弃用 API、参数变更和描述变更。

信息来源： PiAPI Manager GitHub 仓库（Gocyber-world/midjourney-http-v2）中的 Go API.postman_collection.json 契约。该任务会直接从 GitHub 获取此版本化契约，并从 POST /api/v1/task 示例中提取 (model, task_type) 功能。如果 Manager 仓库是私有的，请在 CI 中设置密钥 MCP_SYNC_GITHUB_TOKEN，并为其授予该源仓库的最小权限 contents: read（以及仅用于 MCP 更新自动化的、单独获批的写入权限）。该任务不依赖 Apidog，也会刻意避免检查或报告定价。

命令

npm run build          # compile the MCP server and sync task
npm run test:sync      # offline sync-engine tests (no network or credentials)
npm run sync           # fetch contract and diff baseline; exit 0 = in sync, 2 = drift
npm run sync:snapshot  # print the normalized current contract catalog
npm run sync:report    # write the Markdown drift report to sync-report.md
npm run sync:accept    # after updating src/index.ts, refresh the baseline

默认情况下，npm run sync 使用 Manager GitHub 契约。用于恢复或本地开发时，也可以改用导出的 OpenAPI JSON 文件：

node dist/sync/cli.js diff --file ./piapi-openapi.json

生成漂移报告后，接受基线后，新增功能就已经由相应的、契约支持的 MCP 工具表示。验证 MCP 服务，运行 npm run sync:accept，然后提交更新后的基线。仅当定制针对特定模型的用户体验确有价值时，才更新手写便捷工具。

自动化

.github/workflows/sync-piapi.yml 仅保留供手动触发。 定期同步在获批的本地自动化环境中运行；该环境持有由所有者单独批准的 MCP 凭据，并可在通过敏感信息检查关卡后验证、接受并推送目录更新。

开发

项目结构

piapi-mcp-server/
├── assets/
├── src/
│   ├── index.ts        # Main server entry point
│   └── sync/           # PiAPI -> MCP sync task
│       ├── cli.ts          # CLI: snapshot / diff / accept / report-file
│       ├── fetchers.ts     # GitHub Postman contract + local-file sources
│       ├── normalize.ts    # OpenAPI -> (model, task_type) catalog
│       ├── diff.ts         # catalog diff + Markdown report
│       ├── catalog.ts      # baseline load/save
│       ├── mcp_tools.ts    # catalog -> contract-backed FastMCP tool schemas
│       ├── selftest.ts     # offline engine test (npm run test:sync)
│       ├── types.ts
│       └── baseline.piapi-catalog.json  # committed baseline
├── .github/workflows/sync-piapi.yml     # weekly drift check
├── package.json
├── tsconfig.json
└── .env.example

许可证

MIT