picdefenseio-mcp-server

PicDefense.io MCP サーバー

PicDefense.io API 用の Model Context Protocol サーバーです。AI エージェントが任意の画像 URL に対して、逆画像リスク分析、EXIF/IPTC/XMP メタデータの抽出、画像のバックリンク検索、画像コンテンツの検出（顔／ランドマーク／ロゴ／ラベル／セーフサーチ）を実行できます。

特長

• 🔐 ユーザーごとの認証 — 各接続に個別の PicDefense API トークンを使用します。サーバーがキーを保持することはありません
• 🚀 デュアルトランスポート — 最新の Streamable HTTP（/mcp）と従来の SSE（/sse）に対応
• 🧰 PicDefense API v2 全体を網羅する 11 個のツール
• 🐳 Docker 対応 — nginx を介した本番用コンテナ
• 📖 組み込みドキュメント — /docs の Swagger UI

ツール

ツール	説明
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

トークンは、API（https://app.picdefense.io/api/v2）へのリクエストで X-API-TOKEN ヘッダーとして送信されます。

クイックスタート

ホスト型サーバー（推奨）

ホスト型サーバーは 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 を完全に終了し、再起動してください。

HTTPS ではなく、通常の HTTP サーバー（例：http://<host>:6910）でテストしていますか？ mcp-remote は、ホストが localhost でない限り HTTPS 以外のオリジンをブロックします。args 配列に "--allow-http" を追加するか、SSH トンネルを使って localhost 経由で接続してください。

npx を使ったローカル実行（stdio）— クローン不要

公開済みパッケージを直接実行します。Node.js のインストールが必要です。

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

--api-token の代わりに、PICDEFENSE_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	ストリーム可能な 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 を再実行します。

https://mcp.picdefense.io → 127.0.0.1:6910 で nginx を前段に配置してください （/sse パスでは、proxy_buffering off と長い読み取りタイムアウトを推奨します）。

アーキテクチャ

┌──────────────┐    ┌────────────────────────┐    ┌─────────────────────────┐
│  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 を参照してください。