{
  "markdown": "# PicDefense.io MCP Server\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\n[PicDefense.io](https://picdefense.io) API — let AI agents run reverse-image risk\nanalysis, EXIF extraction, image backlink discovery, and image content\ndetection (face / landmark / logo / label / SafeSearch) on any image URL.\n\n## Features\n\n- 🔐 **Per-user authentication** — each connection carries its own PicDefense API token; the server holds no keys\n- 🚀 **Dual transport** — modern Streamable HTTP (`/mcp`) and legacy SSE (`/sse`)\n- 🧰 **11 tools** covering the full PicDefense API v2\n- 🐳 **Docker-ready** — production container behind nginx\n- 📖 **Built-in docs** — Swagger UI at `/docs`\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `picdefense_get_credits` | Remaining account credit balance |\n| `picdefense_check_image_risk` | Reverse-image risk analysis + **picrisk** score (core tool) |\n| `picdefense_extract_exif` | Extract EXIF metadata (camera, timestamps, GPS) |\n| `picdefense_detect_face` | Detect a human face in an image |\n| `picdefense_detect_landmark` | Detect a recognizable landmark |\n| `picdefense_detect_logo` | Detect a brand logo |\n| `picdefense_safesearch` | Content-safety (adult/violence/racy/…) assessment |\n| `picdefense_find_backlinks` | Find pages where an image appears |\n| `picdefense_detect_labels` | Detect descriptive labels for image contents |\n| `picdefense_extract_text` | Extract text from an image via OCR |\n| `picdefense_detect_watermark` | Detect a visible stock/photographer watermark (source + confidence) |\n\nAll image tools take a single `url` (a public http/https image URL). **Most tools\nconsume account credits per call** — use `picdefense_get_credits` to check your balance.\n\n## Authentication\n\nEvery request authenticates with your PicDefense **API token**, which is your\n**user id and API key joined by a colon**:\n\n```\nUSERID:APIKEY\n```\n\nFind both in your PicDefense.io account settings:\n**https://app.picdefense.io/?returnUrl=https://app.picdefense.io/dashboard/settings**\n\nThe token is sent as the `X-API-TOKEN` header to the API (`https://app.picdefense.io/api/v2`).\n\n## Quick start\n\n### Hosted server (recommended)\n\nThe hosted server runs at **https://mcp.picdefense.io**. Add it to Claude Code:\n\n```bash\n# Streamable HTTP (recommended)\nclaude mcp add -t http picdefense \"https://mcp.picdefense.io/mcp\" \\\n  --header \"X-API-Token: USERID:APIKEY\"\n\n# or SSE\nclaude mcp add -t sse picdefense \"https://mcp.picdefense.io/sse?token=USERID:APIKEY\"\n```\n\nQuick HTTP smoke test:\n\n```bash\ncurl -X POST https://mcp.picdefense.io/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Token: USERID:APIKEY\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\n### Claude Desktop (hosted)\n\nClaude Desktop launches MCP servers as local commands, so reach the hosted server\nthrough the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (requires\nNode.js installed). See [`claude_desktop_config.example.json`](claude_desktop_config.example.json):\n\n```json\n{\n  \"mcpServers\": {\n    \"picdefense\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://mcp.picdefense.io/sse?token=YOUR_USERID:YOUR_APIKEY\"\n      ]\n    }\n  }\n}\n```\n\nEdit your `claude_desktop_config.json` (Settings → Developer → Edit Config), add the\n`mcpServers` block above with your `USERID:APIKEY`, then fully quit and reopen Claude Desktop.\n\n> Testing against a plain-HTTP server (e.g. `http://<host>:6910`) instead of HTTPS?\n> `mcp-remote` blocks non-HTTPS origins unless the host is `localhost` — append\n> `\"--allow-http\"` to the `args` array, or reach it over an SSH tunnel to `localhost`.\n\n### Local (stdio) via npx — no clone needed\n\nRun the published package directly. Requires Node.js installed.\n\n```json\n{\n  \"mcpServers\": {\n    \"picdefense\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@picdefenseio/mcp-server\",\n        \"--api-token\",\n        \"USERID:APIKEY\"\n      ]\n    }\n  }\n}\n```\n\nYou can also pass the token via the `PICDEFENSE_API_TOKEN` env var instead of `--api-token`.\n\n### Local (stdio) from source\n\nClone and build, then point Claude Desktop at the built entry point:\n\n```bash\ngit clone https://github.com/rchanllc/picdefenseio-mcp-server.git\ncd picdefenseio-mcp-server\nnpm install\nnpm run build\n```\n\nThen use `\"command\": \"node\"` with `\"args\": [\"/absolute/path/to/dist/index.js\", \"--api-token\", \"USERID:APIKEY\"]`.\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PICDEFENSE_API_TOKEN` | — | `USERID:APIKEY` (stdio only; hosted server reads it per-connection) |\n| `PICDEFENSE_API_BASE_URL` | `https://app.picdefense.io/api/v2` | API base URL |\n| `PORT` | `6910` | Hosted server listen port |\n\n## Running the hosted server\n\n### Development\n\n```bash\nnpm run dev:sse        # tsx watch, auto-reload\n```\n\n### Production (Docker)\n\n```bash\n# via docker compose\ndocker compose up --build -d\n\n# or the helper script (handles build + health check)\n./deploy.sh\n```\n\nThe container is named `picdefenseio_mcp` and listens on port **6910**.\n\n### HTTP endpoints\n\n| Method | Path | Purpose |\n|--------|------|---------|\n| GET | `/health` | Health check (used by Docker + CI) |\n| GET | `/api/info` | Server + transport info |\n| GET | `/tools` | List available tools |\n| GET | `/docs` | Swagger UI for the underlying API |\n| GET | `/sse?token=USERID:APIKEY` | Open an SSE MCP session |\n| POST | `/messages?sessionId=<id>` | SSE session message channel |\n| POST | `/mcp` | Streamable HTTP MCP (header `X-API-Token`) |\n\n## Self-hosting\n\nThere is no CI/CD in this repo — host it yourself. On your server:\n\n```bash\ngit clone https://github.com/rchanllc/picdefenseio-mcp-server.git\ncd picdefenseio-mcp-server\ndocker compose up --build -d      # or: ./deploy.sh\n```\n\nThe container is named `picdefenseio_mcp` and listens on **6910**. To update,\n`git pull` and re-run `docker compose up --build -d`.\n\nFront it with nginx at `https://mcp.picdefense.io` → `127.0.0.1:6910`\n(`proxy_buffering off` and a long read timeout are recommended for the `/sse` path).\n\n## Architecture\n\n```\n┌──────────────┐    ┌────────────────────────┐    ┌─────────────────────────┐\n│  MCP Client  │───▶│  PicDefense MCP Server │───▶│  PicDefense.io API v2   │\n│ (Claude etc.)│    │      (port 6910)       │    │ app.picdefense.io/api/v2│\n└──────────────┘    └────────────────────────┘    └─────────────────────────┘\n        token (USERID:APIKEY) forwarded as X-API-TOKEN ───────────▶\n```\n\nEach connection builds its own API client + MCP server bound to the caller's token,\nso the service is multi-tenant and stateless with respect to credentials.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 6715,
  "sha": "1feea3847ffa02893179327e8e503373ab0c42bc50418b0b99e4c803b51d2a31",
  "repo_slug": "rchanllc/picdefenseio-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rchanllc_picdefenseio_mcp_serv_06954345/readme"
}