Pics.io plugin

Official plugin and extension distribution for the Pics.io
MCP server.

Pics.io is a digital asset management (DAM) system: a library of collections
and files carrying keywords, faces, ratings, flags, color labels, custom fields
and extracted document text. This repository packages that library as an
installable plugin for AI assistants that speak the
Model Context Protocol, so your assistant
can answer from the approved files your team actually ships instead of guessing.

It is the canonical public surface for five install paths — Claude and
Claude Code, ChatGPT / Codex, Cursor, and Gemini CLI — plus the
bundled skills that teach an assistant how to search a DAM well.

Everything here is read-only. The tools find and describe assets. They never
upload, tag, rate, move, share or delete anything.

What you get

Tools — from the remote MCP server at https://mcp.pics.io/mcp

Every tool is annotated readOnlyHint: true. The exact schemas the server
advertises are mirrored in mcp-manifest.json.

Skills — installed alongside the tools

Commands — Claude Code and Claude

Install

Claude

Settings → Connectors → Add custom connector → https://mcp.pics.io/mcp,
then Connect and sign in to Pics.io.

On a team plan an owner adds the connector once under Organization settings →
Connectors; teammates then connect individually.

Claude Code

claude plugin marketplace add TopTechPhoto/picsio-mcp-plugin
claude plugin install picsio@picsio

Or from inside a session: /plugin marketplace add TopTechPhoto/picsio-mcp-plugin
then /plugin install picsio@picsio.

ChatGPT / Codex

Register the marketplace from your shell:

codex plugin marketplace add TopTechPhoto/picsio-mcp-plugin

Then run /plugins inside a Codex session, find Pics.io, and install it.

Cursor

Add the MCP server in Settings → MCP, or drop this into
.cursor/mcp.json in your project:

{
  "mcpServers": {
    "picsio": { "url": "https://mcp.pics.io/mcp" }
  }
}

Gemini CLI

gemini extensions install https://github.com/TopTechPhoto/picsio-mcp-plugin

Then authenticate:

/mcp auth picsio

Authentication

You need a Pics.io account with access to the library you want to search.

The first request that touches a Pics.io tool starts an OAuth 2.1 flow — your
client opens a browser, you sign in to Pics.io and approve access, and the client
receives a short-lived token. Nothing to paste, no key to store.

The server grants read-only scopes: assets_read, collections_read,
keywords_read, customFields_read. Results are always scoped to what your own
Pics.io account can see, so the plugin can never surface an asset you wouldn't
find in the web app.

Some older MCP clients can't run the OAuth flow. Those can send a Personal API
token (My Account → API → Personal token in Pics.io) as a bearer header via
mcp-remote:

{
  "mcpServers": {
    "picsio": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.pics.io/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer <your-personal-api-token>" }
    }
  }
}

Note the missing space after Authorization: — that's an mcp-remote quirk, not
a typo. Contact [email protected] if you need this path.

Try it

Which Pics.io collections hold our approved brand logos?
Find the hero images from our last product launch.
Show me every 5-star photo tagged for the autumn campaign, newest first.
Any PDFs in the Sales collection that mention "enterprise pricing"?
How do I set up AI keywording in Pics.io?

What this plugin does and doesn't do

Worth stating plainly, because an assistant plugin runs with your data:

• No hooks. Nothing runs on session start, on your prompts, or around your
  tool calls. The plugin is inert until you ask something Pics.io-related.
• No telemetry. This repository ships no analytics, usage pings or crash
  reporting.
• Two network destinations, both expected. Tool calls go to
  https://mcp.pics.io/mcp. The picsio-help-docs skill reads public
  documentation pages on help.pics.io — it sends nothing about your library or
  account to do so.
• Read-only, always. There is no write path. For changes, use the Pics.io
  web app.
• No bundled code runs on your machine. The scripts in scripts/ are
  maintenance tools for this repository, not part of the installed surface.

Repository layout

For maintainers

node scripts/validate.mjs        # manifests, skills, commands, tool references
./scripts/update-help-index.sh   # refresh the bundled Help Center index

Both run in CI on every pull request, plus weekly to catch the endpoint
disappearing. See CONTRIBUTING.md before changing a
manifest — the version, name, description and MCP URL are duplicated across
seven files by design, and validate.mjs enforces that they stay identical.

Links

• Pics.io: https://pics.io
• Help Center: https://help.pics.io/en/
• API reference: https://api.pics.io
• Privacy Policy: https://pics.io/privacy-policy
• Terms of Use: https://pics.io/terms-of-use
• Support: [email protected]

License

This plugin packaging is released under the
Apache License 2.0. Pics.io itself is a commercial service governed
by its own Terms of Use — see NOTICE.