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

Tool	What it does
picsio_search_collections	Find collections by name, path or description, or list the children of one. Returns id, name, description, path, has_child, archived.
picsio_search_assets	Search assets by free text plus ~35 filters — type, keywords, faces, assignees, flag, rating, color label, file size, date ranges, collections — with sorting and paging.
picsio_get_asset	Full metadata for one asset: keywords, description, collections, dimensions, preview URL.
picsio_get_asset_preview	A safe preview URL for one asset. Oversized and unsupported files are rejected with an explanation.

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

Skills — installed alongside the tools

Skill	When it fires
picsio-asset-search	Finding assets and collections in a library. Teaches the collections-first strategy, how to map plain language onto filters, and how to widen a search that came back empty.
picsio-help-docs	Questions about how Pics.io itself works. Locates and reads the right article from the public Help Center at https://help.pics.io/en/ instead of guessing from how other DAMs behave.

Commands — Claude Code and Claude

Command	Does
/picsio:find-assets <what you need>	Runs a collections-first asset search and reports the hits with previews.
/picsio:docs <question>	Answers a how-to question from the Help Center, with links.

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:

This is the beginning of the README. Read the rest at the original. Read the full README ↗