publitio-mcp

MCP (Model Context Protocol) server for the Publitio media hosting, storage & delivery API. Lets AI agents (Claude Code, Claude Desktop, Cursor, n8n MCP client, ...) upload, transform, organize, deliver and manage your media.

Features — 22 tools

• Files: upload (local path or remote URL), list, get, update, delete, build CDN media URLs, download with on-the-fly transformations (resize, crop, quality, grayscale, watermark, video trim / frame extraction) to a local path
• Folders: create, list/tree, rename, delete, public share pages (URL + settings)
• Versions: transcode files (video→mp4/webm/ogv, video→image, video→audio, image conversion, audio waveforms), poll status, reconvert, delete
• Watermarks, Players, Ad Tags, Subtitles: full management
• Stats: delivery statistics for video files

Authentication

Token-based via environment variables — no OAuth needed:

| Variable | Description | |---|---| | PUBLITIO_BEARER_TOKEN | Personal access token from dashboard.publit.io (preferred) | | PUBLITIO_KEY_ID + PUBLITIO_SECRET | API key/secret pair — the server signs each request (SHA-1 signature) |

Set one of the two. Bearer token wins when both are present.

Usage

Claude Code

claude mcp add publitio -e PUBLITIO_BEARER_TOKEN=your_token -- npx -y publitio-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "publitio": {
      "command": "npx",
      "args": ["-y", "publitio-mcp"],
      "env": { "PUBLITIO_BEARER_TOKEN": "your_token" }
    }
  }
}

From a local checkout

cd publitio-mcp
npm install && npm run build
PUBLITIO_BEARER_TOKEN=your_token node dist/index.js

The server speaks MCP over stdio.

Example prompts

• "Upload ~/Pictures/logo.png to Publitio into the marketing folder, public"
• "List my Publitio folders as a tree"
• "Give me a 300x300 cropped grayscale URL for n8nmcp/n8n-test as webp"
• "Convert file Abc123 to 720p mp4 and tell me when it's ready"
• "Download banner.jpg resized to 1200px wide into ./assets/"

Notes

• Stats are available for video files only (Publitio returns 403 otherwise).
• Folder delete removes all files inside it — the tool description warns the agent.
• Watermark/player creation is limited by your Publitio plan quota.
• Errors are returned to the model as readable tool results (isError), so the agent can self-correct.

Development

npm install
npm test        # unit tests (16)
npm run build   # tsc → dist/

License

MIT