Pixapi

pixapi-mcp

通过 MCP 客户端使用 Pixapi 图像和视频生成工具。

• 网站：Pixapi
• 远程 MCP 端点：https://api.pixapi.ai/mcp
• 许可证：MIT

快速开始

自动配置项目（Node.js 22+）：

npx -y pixapi-mcp init --client codex

将 codex 替换为你的客户端，或使用 --client all 配置全部五个客户端：

客户端	--client	配置文件
Claude Code	claude-code	.mcp.json
Cursor	cursor	.cursor/mcp.json
Codex	codex	.codex/config.toml
VS Code / GitHub Copilot	vscode	.vscode/mcp.json
Gemini CLI	gemini-cli	.gemini/settings.json

不指定 --client 时，默认配置 Claude Code 和 Cursor（--client both）。 使用 --project /path/to/project 配置其他项目。

重新加载 MCP 客户端并连接到 pixapi。首次使用时，请完成浏览器登录 和授权提示。客户端会保存 OAuth 会话并自动刷新；无需 API 密钥或编辑凭据。 如果授权被撤销或过期，客户端可能会要求你重新登录。 每个客户端都会管理自己的原生 OAuth 会话。

默认情况下，init 会配置直接远程 HTTP 连接。如果你的客户端提供“添加 MCP 服务”界面， 也可以直接在其中输入端点 URL，无需安装此 npm 包或 Node.js。

Codex 要求项目受信任。在 VS Code 中，使用 MCP: List Servers 启动 pixapi；在 Gemini CLI 中，使用 /mcp 检查它。完成客户端的信任或 登录提示。init 不会更改客户端安全策略。

生成的配置

Claude Code：

{"mcpServers":{"pixapi":{"type":"http","url":"https://api.pixapi.ai/mcp"}}}

Cursor 使用相同的 mcpServers 条目，包含 url，且不包含 type 字段。 VS Code 使用包含 type: "http" 和 url 的 servers。 Gemini CLI 使用包含 httpUrl 的 mcpServers。

Codex：

[mcp_servers.pixapi]
url = "https://api.pixapi.ai/mcp"

运行 init 会更新 pixapi 条目，并保留其他服务和设置。VS Code 的 JSONC 注释会保留。 Codex 的 TOML 设置会保留，但注释和格式不会保留。写入前会解析所有选定的配置； 但如果写入期间发生文件系统故障，仍可能导致部分文件已更新。修复本地问题后重新运行 init。

本地 stdio 桥接

对于需要 stdio 的客户端，请显式配置桥接：

npx -y pixapi-mcp init --client cursor --transport stdio

生成的条目会在不使用凭据的情况下运行 npx -y pixapi-mcp proxy。 通过 npm 注册表安装的 npm 包也会直接启动桥接： 无需单独运行 init 命令或设置环境变量。

桥接会立即完成本地 MCP 握手。首次工具请求时，它会打开浏览器授权， 然后将工具请求转发给 Pixapi。后续连接会重用已保存的会话并自动刷新令牌。 对于工具发现超时较短的客户端，请提前登录一次：

npx -y pixapi-mcp login

如果客户端在首次浏览器登录期间超时，请完成登录并重新连接客户端。 MCP 标准输出或错误输出中不会打印授权 URL、代码或令牌。

OAuth 会话按端点存储在 ~/.pixapi/oauth-<hash>.json 中。 在 macOS 和 Linux 上，目录权限为 0700，文件权限为 0600。 写入操作是原子的；并发运行的桥接进程会共享授权锁。 PKCE 验证器和回调状态仅保存在内存中。回调会绑定到与桥接相同主机上的 loopback 地址。对于无头主机或远程主机，建议使用客户端原生的远程 OAuth 连接。

现有 API 密钥安装

现有的 API 密钥配置仍然兼容。对于显式 API 密钥安装，请在运行 init 时设置 PIXAPI_API_KEY；它会配置 stdio，并将密钥私密保存到 ~/.pixapi/mcp-credentials.json。即使设置了该变量，显式指定 --transport remote 也始终会选择原生 OAuth。代理也可直接接受 PIXAPI_API_KEY，用于无人值守部署。

代理会优先使用显式环境密钥，其次是已保存的 OAuth 会话，最后是旧版密钥文件。若要将现有桥接迁移到 OAuth，请运行 pixapi-mcp login，并从其环境中移除任何 PIXAPI_API_KEY 覆盖项。生成的项目配置中不会包含密钥和令牌。

可用工具

此软件包会转发远程 Pixapi MCP 端点提供的实时工具列表。连接后，调用 tools/list 或 pixapi_get_pricing_and_balance 获取当前目录。

pixapi_get_pricing_and_balance

返回当前余额以及实时图像／视频模型定价。目录中的每一行都包含一个 type：

• 图像：text_to_image、image_to_image
• 视频：text_to_video、image_to_video

标记为 mcp_generate_supported=true 的行可通过对应的生成工具调用。

pixapi_generate_image

启动异步图像任务并返回 task_id。仅使用提示词的请求使用 type=text_to_image，带有 image 字段的请求使用 type=image_to_image。此工具接受实时目录中的图像模型，包括 Gemini、GPT Image、Flux、Seedream、Qwen 和 Wan。

此调用会消耗账户额度。它不是幂等的：重复相同调用会创建另一个任务，并可能再次从账户扣费。

pixapi_generate_video

启动异步视频任务并返回 task_id。仅使用提示词的请求使用 type=text_to_video，带有 image 字段的请求使用 type=image_to_video。请根据所选模型的要求传入 seconds 和 resolution。

此调用会消耗账户额度，且不是幂等的。

pixapi_get_task

获取经过身份验证的账户所拥有的图像或视频任务。使用返回的 task_id 调用此工具进行轮询，直到状态变为 completed 或 failed。已完成的任务会包含媒体 URL。

建议的 Agent 工作流：

1. 调用 pixapi_get_pricing_and_balance。
2. 选择 mcp_generate_supported=true 的目录行，并检查余额。
3. 调用一次 pixapi_generate_image 或 pixapi_generate_video，并保留其 task_id。
4. 每隔几秒轮询一次 pixapi_get_task。
5. 任务完成后返回结果 URL。

CLI 参考

pixapi-mcp init [--client <name|all|both>] [--project <path>] [--transport <remote|stdio>]
pixapi-mcp login
pixapi-mcp proxy
pixapi-mcp --help

不带参数时，此软件包会启动 stdio 代理。

故障排除

• **未显示工具：**重新加载客户端，启用 pixapi 服务，并完成项目信任设置和浏览器登录。对于 stdio，请确保运行桥接的主机上安装了 Node.js 22+，且可使用 npx。
• **授权被拒绝或超时：**从原生客户端重试登录，或运行 pixapi-mcp login 为桥接完成浏览器授权。
• **回调端口不可用：**关闭另一个待处理的 Pixapi 登录，然后重试。
• **服务不可用：**检查连接，稍后重试。公开错误中不会包含内部 HTTP 响应和异常详情。
• **旧版 API 密钥无效：**更换密钥，或按上述说明迁移到 OAuth。

安全和当前限制

• 请勿提交或分享 ~/.pixapi/ 中的文件。
• 请在 Pixapi 账户中撤销未使用或已泄露的凭据。
• stdio 桥接仅转发工具。此软件包不提供资源、提示词、采样和征询功能。
• 图像和视频生成是异步且非幂等的。桥接会在 HTTP 身份验证遭拒时重试一次；对于网络故障或可能发生在工具执行之后的服务器错误，则不会重试。
• 此 MCP 工具不支持账户充值；请在 Pixapi 上完成付款。

如需服务文档，请访问 Pixapi 文档。

官方 MCP Registry

此服务已作为 io.github.Pixapi-AI/pixapi-mcp 发布到官方 MCP Registry，并在 server.json 中声明了两种连接方式：远程端点和 npm 包。两者从版本 0.1.4 开始均支持 OAuth，且无需 API 密钥。

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Pixapi-AI/pixapi-mcp"

推送对应的 v* 标签前，请在 package.json、package-lock.json 和 server.json 中设置匹配的版本。发布工作流会安装锁定的依赖项、运行检查，并在发布前验证 Registry 清单。手动运行时也必须选择该发布标签。重新运行时会比较现有 npm 包的完整性和 Registry 元数据，并且只发布缺失的步骤；如内容冲突，则需要使用新版本。Registry 身份验证使用 GitHub OIDC，无需存储 Registry 令牌。