Pixicular MCP Server

A local Model Context Protocol server that lets an MCP host — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code — analyze images with your own Pixicular account. It runs on your machine over stdio and is a thin, stateless wrapper around the public Pixicular REST API, authenticated with your Pixicular API key.

It is distributed as the npm package pixicular-mcp, so it needs no clone or install step — the host starts it with npx.

Requirements

• Node.js 20 or newer
• A Pixicular API key — create one at https://www.pixicular.com/dashboard/api-keys

Tools

| Tool | Description | REST endpoint | Read-only | | --- | --- | --- | --- | | pixicular_analyze_image_url | Analyze an image from a URL | POST /v1/detect-from-url | No | | pixicular_analyze_image_file | Analyze a local image file | POST /v1/detect | No | | pixicular_list_analyses | List past image analyses | GET /v1/history | Yes | | pixicular_get_analysis | Get a single image analysis by request ID | GET /v1/history/{requestId} | Yes | | pixicular_get_usage | Get current credit usage | GET /v1/usage/current | Yes |

Detection services

Both analyze tools require a services argument. Each selected service costs 1 credit per image, so there is deliberately no default — the choice of what to spend is always explicit.

| Service | Description | Cost | | --- | --- | --- | | detect-labels | Objects, scenes, and concepts in the image | 1 credit | | detect-moderation | Moderation labels (nudity, violence, etc.) | 1 credit | | detect-text | OCR / text extraction | 1 credit | | detect-age | Estimated age ranges of detected faces | 1 credit | | detect-face-emotions | Facial emotion analysis | 1 credit |

Running two services on one image costs 2 credits. pixicular_get_usage costs no credits.

Installation

Claude Code

claude mcp add pixicular --env PIXICULAR_API_KEY=pix_live_your_api_key -- npx -y pixicular-mcp

Claude Desktop

Edit the config file and restart Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pixicular": {
      "command": "npx",
      "args": ["-y", "pixicular-mcp"],
      "env": {
        "PIXICULAR_API_KEY": "pix_live_your_api_key"
      }
    }
  }
}

Cursor

Add the same block to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pixicular": {
      "command": "npx",
      "args": ["-y", "pixicular-mcp"],
      "env": {
        "PIXICULAR_API_KEY": "pix_live_your_api_key"
      }
    }
  }
}

Other MCP hosts (Windsurf, VS Code) use the same command / args / env shape in their own configuration file.

Environment variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | PIXICULAR_API_KEY | Yes | — | Your Pixicular API key | | PIXICULAR_API_URL | No | https://api.pixicular.com | API base URL | | PIXICULAR_TIMEOUT_MS | No | 120000 | Time budget per tool call in milliseconds, including any wait for a queued analysis |

If PIXICULAR_API_KEY is not set, the server prints a one-line error and exits with a non-zero status instead of starting.

Busy periods

When Pixicular is under heavy load, the API may queue an analysis instead of answering right away (HTTP 202 Accepted). The analyze tools then wait for it on their own, polling its status every 2–5 seconds until it completes or fails, so the host still gets the result in one tool call.

• The whole call, upload plus waiting, stays within PIXICULAR_TIMEOUT_MS. If the analysis is still queued or running when that runs out, the tool returns its requestId and status instead of an error. Call pixicular_get_analysis with that requestId later to get the result.
• If the queue is full, the API answers 503 with a Retry-After header. The tool reports how long to wait before retrying. The analysis was not started and no credits were charged.
• A failed analysis is reported with its error code, such as PROVIDER_TIMEOUT or INVALID_IMAGE.

Getting an API key

1. Sign in at https://www.pixicular.com
2. Go to Dashboard → API Keys (https://www.pixicular.com/dashboard/api-keys)
3. Create a key and copy it into your MCP host configuration

Keys are secrets: keep them out of committed configuration files and shared machines. Interactive API documentation lives at https://api.pixicular.com/documentation.

Limits

• pixicular_analyze_image_file: images up to 10 MB; accepted types image/jpeg, image/png, image/webp, image/avif, image/tiff
• Rate limits are keyed on the API key: 60 requests/minute on the analyze endpoints, 600 requests/minute on history

Local development

The server is an npm workspace in the Pixicular monorepo. Build it from the repository root:

npm install
npm run build

Run it directly (it speaks MCP over stdio, so it expects a host on the other end):

PIXICULAR_API_KEY=pix_live_your_api_key node apps/mcp/dist/stdio.js

Inspect and call the tools by hand with the MCP Inspector:

npx @modelcontextprotocol/inspector node apps/mcp/dist/stdio.js

To point an MCP host at the local build instead of the published package, use an absolute path:

claude mcp add pixicular-dev --env PIXICULAR_API_KEY=pix_live_your_api_key \
  -- node /absolute/path/to/pixicular/apps/mcp/dist/stdio.js

The server is built on @modelcontextprotocol/server v2 (the SDK line implementing the 2026-07-28 spec revision) with zod v4 schemas. Compatibility with 2025-era MCP clients is handled by the SDK itself. The server required no changes to apps/api — it only calls public API endpoints.

Privacy Policy

Images and URLs passed to the analyze tools are sent to the Pixicular API for processing and are stored in your account's analysis history, exactly as they would be if you called the REST API directly. The server holds no state of its own and sends nothing anywhere else. See the Pixicular Privacy Policy for what is collected and how long it is kept.

Support

[email protected]