MCP Server

Analyze images with your own Pixicular account from Claude Code, Claude Desktop, Cursor, and other MCP hosts.

Looking for the REST endpoints instead? See the API reference.

Overview

The Pixicular MCP server is a local Model Context Protocol server that lets an MCP host drive your Pixicular account directly — so you can analyze an image and read your history without leaving your editor or chat.

A thin wrapper around the public API

Every tool maps to one endpoint of the same REST API documented in the API reference. The server is stateless and holds no data of its own.

It runs on your machine

The host starts it over stdio and authenticates with your own API key. Nothing is sent anywhere except the Pixicular API.

No clone, no install step

It ships as the npm package pixicular-mcp, started with npx. Requires Node.js 20 or newer.

Tools

Five tools are exposed to the host. Read-only tools never spend credits and never change your account.

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, or its status while pending, by request ID	`GET /v1/history/{requestId}`	Yes
`pixicular_get_usage`	Get current credit usage	`GET /v1/usage/current`	Yes

Installation

Replace pix_live_your_api_key with a key from your dashboard, then restart the host.

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

The host passes these to the server process. Only the API key is required.

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

Without PIXICULAR_API_KEY the server prints a one-line error and exits instead of starting.

Busy Periods & Timeouts

Under heavy load the API may queue an analysis instead of answering right away (HTTP 202, see High Load & Async Processing). From version 1.1.0 the analyze tools handle this for you, so the host still gets the result in one tool call.

It waits and polls automatically

A queued analysis is polled every 2–5 seconds until it completes or fails. The whole tool call, upload plus waiting, stays within PIXICULAR_TIMEOUT_MS (default 120 seconds).

Out of time: fetch the result later

If the analysis is still queued or running when the time is up, the tool returns its requestId and status instead of an error. Call pixicular_get_analysis with that requestId later: it returns the status while the analysis is pending (or its error code if it failed), and the full result once it has completed.

Busy or failed: nothing is charged

If the queue is full (HTTP 503), the tool reports how long to wait before retrying; the analysis was not started. A failed analysis is reported with its error code, such as PROVIDER_TIMEOUT. Credits are charged only for completed analyses.

Upgrade to 1.1.0

Earlier versions do not wait for a queued analysis. With the npx -y pixicular-mcp configuration above, restart your MCP host: a recent npm picks up the latest version when the host starts the server. If you pinned an older version, or an old copy is still used (a global install or an older npm), point args at the latest version and restart the host:

"args": ["-y", "pixicular-mcp@latest"]

Services & Credits

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, so you can check your balance at any time. See Pricing for monthly allowances.

Getting an API Key

The server authenticates with the same API key as the REST API. Keys look like pix_live_….

Sign in to Pixicular

A free account is enough to start.

Create a key

— sign in to create one.

Copy it into your host configuration

Keys are secrets: keep them out of committed configuration files and shared machines. Revoke a key from the dashboard if it is ever exposed.

Privacy & Next Steps

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.

Read the Privacy Policy for what is collected and how long it is kept

Browse the API reference for the endpoints behind each tool

Email us at support@pixicular.com for help