picright-mcp

License-aware image search & insert MCP server. While you write markdown, an agent can search Openverse (CC0/CC-BY/PD), Pixabay and Pexels, check the license against a policy, download the image next to your document, insert it with a proper credit line, and record a provenance ledger (images/provenance.json) of what license was verified at insert time.

Tools

| tool | purpose | |---|---| | search_images | policy-filtered, ranked candidates with normalized license + risk + attribution text | | get_license | full license details / caveats for one candidate | | analyze_document | markdown → indexed blocks so the agent can pick insertion points | | insert_image | download + insert ![alt](images/x.jpg) + credit + ledger entry | | replace_image | swap an inserted image for another candidate | | list_ledger | read provenance.json | | screenshot_url | capture a page/region with headless Chromium — recorded as basis=quotation with source URL + capture date credit | | render_diagram | Mermaid → PNG from the article's own ideas — copyright-clean (basis=original), Korean labels fine | | render_snippet | markdown/HTML snippet + credit for remote clients without a filesystem |

Prompt illustrate bundles the AUTO workflow: analyze → choose stock / screenshot / diagram per spot → insert (last block first).

Policy defaults

usage=commercial (drops CC-NC) · need_modification=true (drops CC-ND) · no_share_alike=true (drops CC-SA) · no_attribution_only=false (set true for CC0/PD/Pixabay/Pexels only).

Install (Claude Code)

claude mcp add picright -- npx -y picright-mcp

Works out of the box with Openverse (no API key). Optional keys widen the pool:

claude mcp add picright \
  -e PIXABAY_API_KEY=... -e PEXELS_API_KEY=... \
  -- npx -y picright-mcp

screenshot_url / render_diagram need a headless Chromium once per machine (everything else works without it):

npx playwright install chromium

Development setup

npm install && npm run build
cp .env.example .env   # optional: PIXABAY_API_KEY, PEXELS_API_KEY (Openverse works without keys)
npm run smoke          # end-to-end check in a temp dir

Then in a session: "이 글에서 이미지가 있으면 좋은 곳을 찾아 상업적 사용 가능한 이미지만 넣어줘" or /picright:illustrate.

Output example

![Autonomous AI agents collaborating](images/robot-teamwork.jpg)

<small>Image: Jane Doe / Pixabay (https://pixabay.com/…) — Pixabay Content License</small>

Notes on sources

• Openverse: CC / public-domain only; API pre-filters with license_type=commercial. CC-BY etc. → TASL attribution generated automatically.
• Pixabay: free commercial use, no attribution required; identifiable people/logos may carry separate rights (surfaced as caveats).
• Pexels: same; the API terms ask for a credit link where possible, so attribution_recommended=true.
• Unsplash intentionally left out of the MVP (hotlink/download-event requirements).

Remote mode (Grok / ChatGPT / claude.ai web)

The same server runs over Streamable HTTP for clients that only accept remote MCP:

PORT=3000 PICRIGHT_TOKEN=<secret> PIXABAY_API_KEY=… PEXELS_API_KEY=… npm run start:http
# → POST http://localhost:3000/mcp   (Authorization: Bearer <secret>)   GET /healthz

Remote clients have no filesystem, so use search_images → render_snippet (returns markdown/HTML with credit + provenance record) instead of insert_image. screenshot_url and render_diagram also work remotely: omit target_file and the PNG is returned inline as an image result.

xAI Grok (Remote MCP tools, Streamable HTTP only):

from xai_sdk import Client, user
from xai_sdk.tools import mcp

client = Client(api_key=XAI_API_KEY)
chat = client.chat.create(
    model="grok-4",
    tools=[mcp(server_url="https://<your-host>/mcp", headers={"Authorization": "Bearer <secret>"})],
)
chat.append(user("이 문단에 어울리는 상업적 사용 가능 이미지 1장을 출처와 함께 markdown으로: ..."))
print(chat.sample().content)

Deploy (Fly.io)

brew install flyctl && fly auth login
fly launch --no-deploy --copy-config --name picright-mcp
fly secrets set PICRIGHT_TOKEN=<secret> PIXABAY_API_KEY=… PEXELS_API_KEY=…
fly deploy

Quick test without deploying: ngrok http 3000.