Picdefenseio Mcp Server

PicDefense.io MCP Server

A Model Context Protocol server for the PicDefense.io API — let AI agents run reverse-image risk analysis, EXIF/IPTC/XMP metadata extraction, image backlink discovery, and image content detection (face / landmark / logo / label / SafeSearch) on any image URL.

Features

• 🔐 Per-user authentication — each connection carries its own PicDefense API token; the server holds no keys
• 🚀 Dual transport — modern Streamable HTTP (/mcp) and legacy SSE (/sse)
• 🧰 11 tools covering the full PicDefense API v2
• 🐳 Docker-ready — production container behind nginx
• 📖 Built-in docs — Swagger UI at /docs

Tools

All image tools take a single url (a public http/https image URL). Most tools consume account credits per call — use picdefense_get_credits to check your balance.

Authentication

Every request authenticates with your PicDefense API token, which is your user id and API key joined by a colon:

USERID:APIKEY

Find both in your PicDefense.io account settings: https://app.picdefense.io/?returnUrl=https://app.picdefense.io/dashboard/settings

The token is sent as the X-API-TOKEN header to the API (https://app.picdefense.io/api/v2).

Quick start

Hosted server (recommended)

The hosted server runs at https://mcp.picdefense.io. Add it to Claude Code:

# Streamable HTTP (recommended)claude mcp add -t http picdefense "https://mcp.picdefense.io/mcp" \  --header "X-API-Token: USERID:APIKEY"
# or SSEclaude mcp add -t sse picdefense "https://mcp.picdefense.io/sse?token=USERID:APIKEY"

Quick HTTP smoke test:

curl -X POST https://mcp.picdefense.io/mcp \  -H "Content-Type: application/json" \  -H "X-API-Token: USERID:APIKEY" \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude Desktop (hosted)

Claude Desktop launches MCP servers as local commands, so reach the hosted server through the mcp-remote bridge (requires Node.js installed). See claude_desktop_config.example.json:

{  "mcpServers": {    "picdefense": {      "command": "npx",      "args": [        "-y",        "mcp-remote",        "https://mcp.picdefense.io/sse?token=YOUR_USERID:YOUR_APIKEY"      ]    }  }}

Edit your claude_desktop_config.json (Settings → Developer → Edit Config), add the mcpServers block above with your USERID:APIKEY, then fully quit and reopen Claude Desktop.

Testing against a plain-HTTP server (e.g. http://<host>:6910) instead of HTTPS? mcp-remote blocks non-HTTPS origins unless the host is localhost — append "--allow-http" to the args array, or reach it over an SSH tunnel to localhost.

Local (stdio) via npx — no clone needed

Run the published package directly. Requires Node.js installed.

{  "mcpServers": {    "picdefense": {      "command": "npx",      "args": [        "-y",        "@picdefenseio/mcp-server",        "--api-token",        "USERID:APIKEY"      ]    }  }}

You can also pass the token via the PICDEFENSE_API_TOKEN env var instead of --api-token.

Local (stdio) from source

Clone and build, then point Claude Desktop at the built entry point:

git clone https://github.com/rchanllc/picdefenseio-mcp-server.gitcd picdefenseio-mcp-servernpm installnpm run build

Then use "command": "node" with "args": ["/absolute/path/to/dist/index.js", "--api-token", "USERID:APIKEY"].

Configuration

Running the hosted server

Development

npm run dev:sse        # tsx watch, auto-reload

Production (Docker)

# via docker composedocker compose up --build -d
# or the helper script (handles build + health check)./deploy.sh

The container is named picdefenseio_mcp and listens on port 6910.

HTTP endpoints

Self-hosting

There is no CI/CD in this repo — host it yourself. On your server:

git clone https://github.com/rchanllc/picdefenseio-mcp-server.gitcd picdefenseio-mcp-serverdocker compose up --build -d      # or: ./deploy.sh

The container is named picdefenseio_mcp and listens on 6910. To update, git pull and re-run docker compose up --build -d.

Front it with nginx at https://mcp.picdefense.io → 127.0.0.1:6910 (proxy_buffering off and a long read timeout are recommended for the /sse path).

Architecture

┌──────────────┐    ┌────────────────────────┐    ┌─────────────────────────┐│  MCP Client  │───▶│  PicDefense MCP Server │───▶│  PicDefense.io API v2   ││ (Claude etc.)│    │      (port 6910)       │    │ app.picdefense.io/api/v2│└──────────────┘    └────────────────────────┘    └─────────────────────────┘        token (USERID:APIKEY) forwarded as X-API-TOKEN ───────────▶

Each connection builds its own API client + MCP server bound to the caller's token, so the service is multi-tenant and stateless with respect to credentials.

License

MIT — see LICENSE.