picdefenseio-mcp-server

PicDefense.io MCP 服务

一个用于 PicDefense.io API 的 Model Context Protocol 服务，让 AI Agent 可以对任意图片 URL 进行反向图片风险分析、EXIF/IPTC/XMP 元数据提取、图片反向链接发现，以及图片内容检测（人脸 / 地标 / 徽标 / 标签 / SafeSearch）。

功能

• 🔐 按用户身份验证 — 每个连接都携带各自的 PicDefense API 令牌；服务不保存任何密钥
• 🚀 双传输方式 — 现代 Streamable HTTP（/mcp）和旧版 SSE（/sse）
• 🧰 11 个工具 — 覆盖完整的 PicDefense API v2
• 🐳 支持 Docker — 通过 nginx 提供生产环境容器
• 📖 内置文档 — Swagger UI 位于 /docs

工具

工具	描述
picdefense_get_credits	查看账户剩余积分余额
picdefense_check_image_risk	反向图片风险分析 + picrisk 评分（核心工具）
picdefense_extract_exif	提取 EXIF 元数据（相机、时间戳、GPS）以及 IPTC/XMP 版权、创作者、署名和许可方字段
picdefense_detect_face	检测图片中的人脸
picdefense_detect_landmark	检测可识别的地标
picdefense_detect_logo	检测品牌徽标
picdefense_safesearch	内容安全评估（成人内容 / 暴力 / 情色内容 / …）
picdefense_find_backlinks	查找图片出现过的网页
picdefense_detect_labels	检测图片内容的描述性标签
picdefense_extract_text	通过 OCR 从图片中提取文本
picdefense_detect_watermark	检测可见的图库 / 摄影师水印（来源 + 置信度）

所有图片工具都只需传入一个 url（公开的 http/https 图片 URL）。大多数工具每次调用都会消耗账户积分 — 使用 picdefense_get_credits 查看余额。

身份验证

每个请求都使用你的 PicDefense API 令牌进行身份验证，令牌由你的用户 ID 和 API 密钥以冒号连接组成：

USERID:APIKEY

可在 PicDefense.io 账户设置中找到这两项： https://app.picdefense.io/?returnUrl=https://app.picdefense.io/dashboard/settings

令牌通过 X-API-TOKEN 请求头发送至 API（https://app.picdefense.io/api/v2）。

快速开始

托管服务（推荐）

托管服务运行于 **https://mcp.picdefense.io**。将其添加到 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"

快速 HTTP 冒烟测试：

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（托管）

Claude Desktop 会以本地命令的形式启动 MCP 服务，因此需要通过 mcp-remote 桥接程序连接托管服务（需要安装 Node.js）。请参阅 claude_desktop_config.example.json：

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

编辑你的 claude_desktop_config.json（Settings → Developer → Edit Config），添加上方的 mcpServers 配置块，并填入你的 USERID:APIKEY，然后完全退出并重新打开 Claude Desktop。

要连接纯 HTTP 服务（例如 http://<host>:6910），而不是 HTTPS？ 除非主机是 localhost，否则 mcp-remote 会阻止非 HTTPS 源 — 将 "--allow-http" 追加到 args 数组，或通过 SSH 隧道连接到 localhost。

通过 npx 在本地运行（stdio）— 无需克隆

直接运行已发布的软件包。需要安装 Node.js。

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

也可以通过 PICDEFENSE_API_TOKEN 环境变量传入令牌，而不是使用 --api-token。

从源代码在本地运行（stdio）

克隆并构建，然后将 Claude Desktop 指向构建后的入口文件：

git clone https://github.com/rchanllc/picdefenseio-mcp-server.git
cd picdefenseio-mcp-server
npm install
npm run build

然后使用 "command": "node"，并将 "args": ["/absolute/path/to/dist/index.js", "--api-token", "USERID:APIKEY"] 设为参数。

配置

变量	默认值	描述
PICDEFENSE_API_TOKEN	—	USERID:APIKEY（仅用于 stdio；托管服务会按连接读取）
PICDEFENSE_API_BASE_URL	https://app.picdefense.io/api/v2	API 基础 URL
PORT	6910	托管服务监听端口

运行托管服务

开发

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

生产环境（Docker）

# via docker compose
docker compose up --build -d

# or the helper script (handles build + health check)
./deploy.sh

容器名为 picdefenseio_mcp，监听端口 6910。

HTTP 端点

方法	路径	用途
GET	/health	健康检查（Docker 和 CI 使用）
GET	/api/info	服务端和传输方式信息
GET	/tools	列出可用工具
GET	/docs	底层 API 的 Swagger UI
GET	/sse?token=USERID:APIKEY	打开 SSE MCP 会话
POST	/messages?sessionId=<id>	SSE 会话消息通道
POST	/mcp	Streamable HTTP MCP（请求头 X-API-Token）

自托管

此仓库没有 CI/CD，请自行托管。在你的服务器上：

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

容器名为 picdefenseio_mcp，监听端口 6910。要更新，请运行 git pull，然后重新运行 docker compose up --build -d。

在前面配置 nginx，使 https://mcp.picdefense.io 指向 127.0.0.1:6910 （建议对 /sse 路径关闭 proxy_buffering 并设置较长的读取超时）。

架构

┌──────────────┐    ┌────────────────────────┐    ┌─────────────────────────┐
│  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 ───────────▶

每个连接都会创建自己的 API 客户端和绑定到调用方令牌的 MCP 服务， 因此该服务支持多租户，且凭据无状态。

许可证

MIT — 参见 LICENSE。