picgo-mcp

Quick start: Send the following prompt to your Coding Agent: 请从 https://github.com/timerring/PicGo-MCP 安装并配置 PicGo MCP Server。

An MCP stdio server that embeds PicGo Core directly into the process. It lets MCP clients such as Codex and Claude Desktop reuse existing PicGo image hosting configurations, without requiring the PicGo desktop app to run and without going through 127.0.0.1:36677.

Features

• Directly invokes PicGo Core 3, with no desktop app dependency.

• Supports local files, file:// URLs, and HTTP(S) image URLs.

• Supports single image uploads and batch uploads of up to 20 images.

• Automatically discovers PicGo Desktop, PicGo Core, and CLI configurations.

• Supports custom uploaded file names and return formats.

• Concurrent calls are automatically queued to prevent PicGo's mutable upload state from interfering with each other.

• Status tools do not return config values such as tokens or secrets, and display the user's home directory as ~.

Related MCP server: flin-imgbb-mcp

Requirements

• Node.js >=20.19.0

• A working PicGo configuration file

Installation

Install from source:

npm install
npm run build
npm install -g .

Verify the command is available:

picgo-mcp --help

Installing into Codex

codex mcp add picgo -- picgo-mcp
codex mcp get picgo

After adding the new MCP server, start a new task or refresh the client so the tool list reloads.

Other MCP clients

After a global install, the following stdio configuration can be used:

{
  "mcpServers": {
    "picgo": {
      "command": "picgo-mcp"
    }
  }
}

When the config file needs to be explicitly specified:

{
  "mcpServers": {
    "picgo": {
      "command": "picgo-mcp",
      "args": ["--config", "/path/to/picgo/config.json"]
    }
  }
}

You can also set the environment variable PICGO_CONFIG_PATH. --config takes precedence over the environment variable and automatic discovery.

PicGo configuration

The following locations are searched in order:

• macOS：~/Library/Application Support/picgo/data.json

• Windows：%APPDATA%/picgo/data.json

• Linux：$XDG_CONFIG_HOME/picgo/data.json or ~/.config/picgo/data.json

• All platforms: ~/.picgo/config.json

GitHub image hosting example

The following example uploads images to the repository's images/ directory and returns CDN URLs via jsDelivr:

{
  "picBed": {
    "uploader": "github",
    "current": "github",
    "github": {
      "repo": "OWNER/REPOSITORY",
      "branch": "main",
      "path": "images/",
      "customUrl": "https://cdn.jsdelivr.net/gh/OWNER/REPOSITORY@main",
      "token": "YOUR_GITHUB_TOKEN"
    }
  },
  "picgoPlugins": {},
  "settings": {
    "picgoMcp": {
      "uploadNameTemplate": "${dateTime}-${fileName}${extName}",
      "outputFormat": "${url}"
    }
  }
}

The GitHub token needs write access to the target repository. Do not commit real tokens to Git, issues, logs, or chat history, and restrict the config file permissions to be readable only by the current user:

chmod 600 ~/.picgo/config.json

When PicGo Core 3 reads a legacy config for the first time, it may fill in an uploader config and internal metadata; this is normal automatic migration behavior.

File name templates

Configuration location:

{
  "settings": {
    "picgoMcp": {
      "uploadNameTemplate": "${dateTime}-${fileName}${extName}"
    }
  }
}

Supported variables:

Recommended:

${dateTime}-${fileName}${extName}

Using only ${dateTime}${extName} can cause name collisions for images uploaded within the same second. Templates only perform whitelist placeholder replacement, do not execute JavaScript, and do not allow extra paths such as ../ to be written through the file name; remote directories should be set using the uploader's path config.

Output template

Configuration location:

{
  "settings": {
    "picgoMcp": {
      "outputFormat": "${url}"
    }
  }
}

Supported variables:

• ${url}: the URL of the uploaded image.

• ${uploadedName}: the uploaded file name, without extension.

Common formats:

${url}
![${uploadedName}](${url})

Tool responses always include image info, a URL array, Markdown, and a formattedOutput generated from the template, so callers can choose the fields they need.

MCP tools

upload_image

Upload a local or remote image:

{
  "source": "/path/to/image.png"
}

upload_images

Batch upload 1–20 images:

{
  "sources": [
    "/path/to/first.png",
    "https://example.com/second.jpg"
  ]
}

get_picgo_status

Returns whether a config exists, the PicGo version, the current uploader, configured field names, and available uploaders. This tool does not return config values or image-hosting credentials.

Sample upload result

{
  "images": [
    {
      "url": "https://cdn.example.com/images/2026-08-23-17-34-47-example.png",
      "fileName": "2026-08-23-17-34-47-example.png",
      "width": 800,
      "height": 600,
      "size": 123456
    }
  ],
  "urls": [
    "https://cdn.example.com/images/2026-08-23-17-34-47-example.png"
  ],
  "markdown": "![2026-08-23-17-34-47-example.png](https://cdn.example.com/images/2026-08-23-17-34-47-example.png)",
  "formattedOutput": "https://cdn.example.com/images/2026-08-23-17-34-47-example.png"
}

How it works

MCP clients typically start a picgo-mcp stdio process and reuse it for the duration of the client session. Images are read and image source/hosting services are only accessed when an upload tool is called; once the client closes the connection, the server process exits and releases memory.

PicGo holds mutable input and output state on the instance, so this project serializes concurrent upload requests.

Security notes

• Do not pass tokens in command arguments; credentials should be managed by the PicGo config.

• MCP tools do not return image-hosting credentials; status tools only return field names.

• Home directory paths are replaced with ~ in tool responses.

• HTTP(S) images are first downloaded by PicGo, then uploaded to the configured image-hosting service.

• PicGo loads plugins according to its config; only install and enable trusted plugins.

• Do not expose the stdio server to untrusted clients.

Development and verification

npm install
npm test
npm run check
npm run build

Testing currently covers config discovery, MCP tool registration, status redaction, upload input validation, naming templates, output templates, and privacy checks for hosted files.

License

MIT