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 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`	Request timeout in milliseconds

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

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

Go to Dashboard → API Keys and generate 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