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 OAuth, even if that variable is set. The proxy also accepts PIXAPI_API_KEY directly for unattended deployments.

The proxy gives an explicit environment key priority, then a saved OAuth session, then a legacy key file. To migrate an existing bridge to OAuth, run pixapi-mcp login and remove any PIXAPI_API_KEY override from its environment. Keys and tokens never appear in generated project configurations.

Available tools

This package forwards the live tool list from the remote Pixapi MCP endpoint. After you connect, call tools/list or pixapi_get_pricing_and_balance for the current catalog.

pixapi_get_pricing_and_balance

Returns your current balance and live image/video model pricing. Each catalog row includes a type:

• Images: text_to_image, image_to_image
• Videos: text_to_video, image_to_video

Rows marked mcp_generate_supported=true can be called through the matching generate tool.

pixapi_generate_image

Starts an asynchronous image task and returns a task_id. Use type=text_to_image for a prompt-only request, or type=image_to_image with the image field. The tool accepts the image models in the live catalog, including Gemini, GPT Image, Flux, Seedream, Qwen, and Wan.

This call consumes account credits. It is not idempotent: repeating the same call creates another task and may charge the account again.

pixapi_generate_video

Starts an asynchronous video task and returns a task_id. Use type=text_to_video for a prompt-only request, or type=image_to_video with the image field. Pass seconds and resolution as required by the selected model.

This call consumes account credits and is not idempotent.

pixapi_get_task

Retrieves an image or video task owned by the authenticated account. Poll this tool with the returned task_id until the status is completed or failed. A completed task includes media URLs.

Recommended agent flow:

1. Call pixapi_get_pricing_and_balance.
2. Select a catalog row with mcp_generate_supported=true and check the balance.
3. Call pixapi_generate_image or pixapi_generate_video once and retain its task_id.
4. Poll pixapi_get_task every few seconds.
5. Return the result URL when the task is complete.

CLI reference

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

With no arguments, the package starts the stdio proxy.

Troubleshooting

• Tools do not appear: reload the client, enable the pixapi server, and complete project trust and browser sign-in. For stdio, ensure Node.js 22+ and npx are available on the host running the bridge.
• Authorization denied or timed out: retry sign-in from the native client, or run pixapi-mcp login for the bridge and complete browser authorization.
• Callback port unavailable: close another pending Pixapi login and retry.
• Service unavailable: check your connection and retry later. Internal HTTP responses and exception details are omitted from public errors.
• Invalid legacy API key: replace the key, or migrate to OAuth as above.

Security and current limitations

• Do not commit or share files in ~/.pixapi/.
• Revoke unused or exposed credentials in your Pixapi account.
• The stdio bridge forwards tools only. Resources, prompts, sampling, and elicitation are not exposed by this package.
• Image and video generation are asynchronous and not idempotent. The bridge retries HTTP authentication rejection once; it does not retry network failures or server errors that might have occurred after a tool executed.
• Account top-up is not exposed as an MCP tool; complete payment on Pixapi.

For service documentation, visit Pixapi docs.

Official MCP Registry

This server is published to the official MCP Registry as io.github.Pixapi-AI/pixapi-mcp, with both connection methods declared in server.json: the remote endpoint and the npm package. Both support OAuth without a required API key starting with version 0.1.4.

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

Set matching versions in package.json, package-lock.json, and server.json before pushing the corresponding v* tag. The release workflow installs locked dependencies, runs checks, and validates the Registry manifest before publishing. Manual runs must also select that release tag. A rerun compares existing npm package integrity and Registry metadata and only publishes missing steps; conflicting contents require a new version. Registry authentication uses GitHub OIDC, without a stored Registry token.