# 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](https://docs.astral.sh/uv/) (no install step):

```bash
uvx clipgrab-mcp
```

Or install with pip:

```bash
pip install clipgrab-mcp
clipgrab-mcp
```

## Setup from source

```bash
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)

```bash
./.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:

```bash
npm install -g @vscode/vsce
vsce package
```

## VS Code configuration (without the extension)

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

```jsonc
{
  "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:

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

ClipGrab is described for registries by [`server.json`](server.json) and is
published to the [official MCP registry](https://github.com/modelcontextprotocol/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