clipgrab-mcp 0.1.0

Save the system clipboard image to a file via an MCP server, for AI agents that can read image files but not the clipboard.

ClipGrab

mcp-name: io.github.ulebule/clipgrab

An MCP server that saves the image currently on the system clipboard to a file (PNG or JPG).

Why

Many AI agents can read image files but cannot access the system clipboard. ClipGrab bridges that gap: copy an image (e.g. a screenshot), call the tool, and get back a path to a saved image on disk that the agent can open.

By default the image is saved to the current working directory — the folder the agent runs from.

Requirements

• Python 3.10+
• Python packages (see requirements.txt): Pillow, mcp[cli]
• Linux only: wl-clipboard (wl-paste) or xclip for the clipboard fallback.

Install from PyPI

Run directly with uv (no install step):

uvx clipgrab-mcp

Or install with pip:

pip install clipgrab-mcp
clipgrab-mcp

Setup from source

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Tools

• save_clipboard_image(directory?, filename?, image_format?) → saves the clipboard image and returns the absolute path.
  • directory — defaults to the current working directory (created if missing). Can also be set via the CLIPGRAB_DEFAULT_DIR environment variable.
  • filename — defaults to a timestamped name (clipboard-YYYYMMDD-HHMMSS).
  • image_format — "png" (default) or "jpg".
• clipboard_has_image() → returns true/false.

Run manually (stdio)

./.venv/bin/python mcp_server.py

Install as a VS Code extension

ClipGrab ships as a VS Code extension that registers the MCP server automatically — it then appears under Extensions view → MCP Servers and starts on demand. On first use the extension creates its own Python virtual environment and installs the dependencies, so you only need Python 3.10+ on your PATH (configurable via the clipgrab.pythonPath setting).

Develop / try it:

1. Open this folder in VS Code and press F5 to launch the Extension Development Host.
2. In that window, open Chat (agent mode); the ClipGrab MCP server and its save_clipboard_image tool are available.

Package a .vsix for sharing:

npm install -g @vscode/vsce
vsce package

VS Code configuration (without the extension)

A ready-to-use config lives in .vscode/mcp.json:

{
  "servers": {
    "clipgrab": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Then open .vscode/mcp.json and start the clipgrab server (or use the Command Palette → "MCP: List Servers").

Use with an MCP client

Point any MCP client at the published PyPI package over stdio:

{
  "servers": {
    "clipgrab": {
      "command": "uvx",
      "args": ["clipgrab-mcp"]
    }
  }
}

ClipGrab is described for registries by server.json and is published to the official MCP registry under the name io.github.ulebule/clipgrab.

Technical notes

• Cross-platform image grab: Pillow ImageGrab.grabclipboard() (Windows / macOS, and Linux with a recent Pillow). On Linux it falls back to wl-paste / xclip.

License

MIT