pixapi-mcp

Use Pixapi image and video generation tools from MCP clients.

• Website: Pixapi
• Remote MCP endpoint: https://api.pixapi.ai/mcp
• License: MIT

Quick start

Configure your project automatically (Node.js 22+):

npx -y pixapi-mcp init --client codex

Replace codex with your client, or use --client all for all five:

Without --client, the default is Claude Code and Cursor (--client both). Use --project /path/to/project to configure another project.

Reload your MCP client and connect to pixapi. Complete its browser sign-in and authorization prompt the first time. The client saves the OAuth session and refreshes it automatically; no API key or credential editing is required. The client may ask you to sign in again if authorization is revoked or expires. Each client manages its own native OAuth session.

init configures a direct remote HTTP connection by default. If your client has an Add MCP Server interface, you can also enter the endpoint URL there without installing this npm package or Node.js.

Codex requires a trusted project. In VS Code, use MCP: List Servers to start pixapi; in Gemini CLI, use /mcp to inspect it. Complete any client trust or sign-in prompt. init does not change client security policies.

Generated configuration

Claude Code:

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

Cursor uses the same mcpServers entry with url and no type field. VS Code uses servers with type: "http" and url. Gemini CLI uses mcpServers with httpUrl.

Codex:

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

Running init updates the pixapi entry and preserves other servers and settings. VS Code JSONC comments are preserved. Codex TOML settings are preserved, but comments and formatting are not. All selected configurations are parsed before writing; a filesystem failure during writes can still leave some files updated. Correct the local issue and rerun init.

Local stdio bridge

For clients that need stdio, configure the bridge explicitly:

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

The generated entry runs npx -y pixapi-mcp proxy without credentials. Registry installations of the npm package also start the bridge directly: no separate init command or environment variable is required.

The bridge completes the local MCP handshake immediately. On the first tool request it opens browser authorization, then forwards tools to Pixapi. Subsequent connections reuse the saved session and refresh tokens automatically. For clients with a short tool-discovery timeout, sign in once beforehand:

npx -y pixapi-mcp login

If a client times out during the initial browser sign-in, complete sign-in and reconnect the client. No authorization URL, code, or token is printed to MCP stdout or error output.

OAuth sessions are stored per endpoint in ~/.pixapi/oauth-<hash>.json. On macOS and Linux, the directory uses mode 0700 and files use 0600. Writes are atomic; concurrent bridge processes share an authorization lock. PKCE verifiers and callback state are kept only in memory. The callback binds to loopback on the same host as the bridge. For a headless or remote host, prefer the client's native remote OAuth connection.

Existing API key installations

Existing API key configurations remain compatible. For an explicit API key installation, set PIXAPI_API_KEY when running init; it configures stdio and saves the key privately in ~/.pixapi/mcp-credentials.json. An explicit --transport remote always selects native OA

... View full README on GitHub