pixapi-mcp

pixapi-mcp

Use Pixapi image-generation tools from any Model Context Protocol (MCP) client.

• Website: https://pixapi.ai
• Documentation: https://pixapi.ai/docs
• Remote MCP endpoint: https://api.pixapi.ai/mcp

Pixapi currently provides tools for checking model pricing and account balance, starting an asynchronous image-generation task, and retrieving its result.

Choose the right connection method

Remote MCP with OAuth — recommended

If your client supports remote MCP servers and OAuth, add this URL directly:

https://api.pixapi.ai/mcp

Your client opens Pixapi in a browser so you can sign in and authorize it. You do not need this npm package, Node.js, or an API key for that connection method.

Local stdio bridge

Use this npm package when your MCP client only supports local stdio servers. The bridge reads a Pixapi API key from a private file and forwards MCP tool requests to the remote Pixapi MCP endpoint.

Requirements:

• Node.js 22 or newer
• A Pixapi account
• A Pixapi API key created at https://pixapi.ai/settings/apikeys

Quick start

1. Create an API key

Sign in to Pixapi, open API Keys, create a key, and copy it. Treat the key like a password.

2. Configure your MCP client

Run the command from the project in which you want to enable Pixapi.

macOS or Linux:

PIXAPI_API_KEY='sk_your_key' npx -y pixapi-mcp init

Windows PowerShell:

$env:PIXAPI_API_KEY = 'sk_your_key'
npx -y pixapi-mcp init
Remove-Item Env:PIXAPI_API_KEY

By default, init configures both Claude Code and Cursor:

• Claude Code: .mcp.json
• Cursor: .cursor/mcp.json

Configure only one client:

PIXAPI_API_KEY='sk_your_key' npx -y pixapi-mcp init --client claude-code
PIXAPI_API_KEY='sk_your_key' npx -y pixapi-mcp init --client cursor

Configure another project directory:

PIXAPI_API_KEY='sk_your_key' npx -y pixapi-mcp init \
  --project /path/to/project

Restart or reload your MCP client after configuration. The client starts the bridge with:

npx -y pixapi-mcp proxy

You normally do not need to run proxy yourself.

Generated configuration

The generated client entry contains no API key:

{
  "mcpServers": {
    "pixapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pixapi-mcp", "proxy"]
    }
  }
}

The API key is stored separately at:

~/.pixapi/mcp-credentials.json

On macOS and Linux, the directory is set to mode 0700 and the credential file to mode 0600. The key is sent only to the HTTPS Pixapi MCP endpoint in an Authorization header. It is not written to .mcp.json or .cursor/mcp.json.

Running init again replaces the stored Pixapi credential and updates only the pixapi MCP server entry. Other MCP servers and top-level fields in the configuration files are preserved.

Available tools

pixapi_get_pricing_and_balance

Returns your current balance and live image/video model pricing. Models currently supported by the MCP image-generation tool are marked with mcp_generate_supported=true.

pixapi_generate_image

Starts an asynchronous text-to-image task and returns a task_id. The current MCP release accepts the supported Gemini image models exposed by the tool schema.

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

pixapi_get_task

Retrieves a 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 the generated image URL.

Recommended agent flow:

• Call pixapi_get_pricing_and_balance.
• Select a model marked mcp_generate_supported=true and check the balance.
• Call pixapi_generate_image once and retain its task_id.
• Poll pixapi_get_task every few seconds.
• Return the result URL when the task is complete.

CLI reference

pixapi-mcp init [options]
pixapi-mcp proxy
pixapi-mcp --help

init options:

--project <path>            Project to configure (default: current directory)
--client <both|claude-code|cursor>
--help                      Show command help

For this release, set PIXAPI_API_KEY when running init.

Troubleshooting

PIXAPI_API_KEY is required

Create a key at https://pixapi.ai/settings/apikeys and set it only for the init command as shown above.

Invalid Pixapi API key

Verify that you copied the complete key and that it starts with sk_. Create a replacement key if the original is no longer available.

ENOENT ... mcp-credentials.json

The bridge has not been initialized for this user account. Run init before starting or reloading the MCP client.

The tools do not appear

Restart the MCP client after running init. Confirm that Node.js 22 or newer and npx are available in the environment used by the client:

node --version
npx --version
npx -y pixapi-mcp --help

Also confirm that the project contains .mcp.json or .cursor/mcp.json.

Authentication fails after setup

The stored key may have been revoked. Create a new key, run init again, and restart the MCP client.

Security and current limitations

• Do not commit or share ~/.pixapi/mcp-credentials.json.
• Revoke unused or exposed keys in your Pixapi account.
• The stdio bridge currently forwards MCP tools only. Resources, prompts, sampling, and elicitation are not exposed by this package.
• Image generation is asynchronous and currently not idempotent.
• Image editing, video generation, and account top-up are not exposed as MCP tools in this initial release.
• The package is provided under a proprietary, unlicensed distribution (UNLICENSED). Use is subject to Pixapi's applicable service terms.

For API behavior, models, pricing, and service documentation, visit https://pixapi.ai/docs.