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 SSE

claude 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:// :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.git

cd picdefenseio-mcp-server npm install npm 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 compose

docker 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.git

cd picdefenseio-mcp-server docker 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.