# Allscreenshots Plugin

Take website screenshots from Claude Code, OpenAI Codex, and any MCP-compatible client via the Allscreenshots API.

## Supported Platforms

- Claude Code
- OpenAI Codex
- MCP-compatible clients such as Cursor, VS Code Copilot, Gemini CLI, and Windsurf

## Quick Install

### Claude Code

Add the Allscreenshots marketplace, then install the plugin:

```bash
/plugin marketplace add allscreenshots/allscreenshots-plugin
/plugin install allscreenshots@allscreenshots
```

Restart Claude Code after installation. The Claude Code marketplace installs a small plugin package from `claude-code-plugin/`.

If you already installed an older version and Claude Code still reports a plugin cache error, refresh the marketplace and update the plugin:

```bash
/plugin marketplace update allscreenshots
/plugin update allscreenshots@allscreenshots
```

### OpenAI Codex

Add the Allscreenshots marketplace, then install the plugin from Codex's plugin directory:

```bash
codex plugin marketplace add allscreenshots/allscreenshots-plugin
codex
/plugins
```

Choose the Allscreenshots marketplace, open the Allscreenshots plugin, and install it. The plugin bundles the MCP server configuration, so you do not need to paste a long `codex mcp add` command.

If you already installed an older version, refresh the marketplace first:

```bash
codex plugin marketplace upgrade allscreenshots
```

### Generic MCP Client

Configure your MCP client to run:

```bash
python3 /path/to/allscreenshots-plugin/mcp_server/server.py
```

Set an API key in the MCP server environment or pass it through the `api_key` tool parameter.

## Configuration

Get an API key from:

```text
https://allscreenshots.com/dashboard
```

Then set it as an environment variable:

```bash
export ALLSCREENSHOTS_API_KEY=your-key-here
```

You can also pass an API key directly through the `api_key` parameter when calling `take_screenshot`.

The MCP server reads `ALLSCREENSHOTS_API_KEY` when that variable is visible to the MCP subprocess. You can also pass an API key directly through the `api_key` parameter when calling `take_screenshot`.

If the MCP tool is unavailable, the Allscreenshots REST API can be called directly with `curl`; no Allscreenshots CLI is required.

## Available Tools

| Tool | Description | Parameters |
| --- | --- | --- |
| `take_screenshot` | Captures a website screenshot and returns the saved local file path. | `url`, `api_key`, `width`, `height`, `format`, `full_page`, `delay`, `dark_mode`, `block_ads` |
| `get_api_info` | Returns setup links, supported formats, rate limit notes, and API key guidance. | None |

## Examples

- "Take a screenshot of https://example.com"
- "Capture a full-page screenshot of our landing page"
- "Screenshot this page in dark mode"
- "Take a mobile screenshot of https://example.com"
- "Grab a screenshot without ads or cookie banners"
- "How do I get an Allscreenshots API key?"

## Development

### Official MCP Registry

The hosted MCP server is registered as `com.allscreenshots/allscreenshots`:

https://registry.modelcontextprotocol.io/v0.1/servers/com.allscreenshots%2Fallscreenshots/versions/latest

`server.json` is the publishing manifest. The endpoint remains
`https://mcp.allscreenshots.com/mcp/v1`, with OAuth sign-in or an optional `X-API-Key` header.

To publish an updated version, bump `version` in `server.json`, commit it, and run
the **Publish to MCP registry** workflow. It authenticates ownership through
`https://allscreenshots.com/.well-known/mcp-registry-auth`. The matching Ed25519
private seed is held in the `MCP_REGISTRY_PRIVATE_KEY` repository secret; never
commit that key. GitHub OIDC authentication only grants `io.github.*` namespaces
and cannot publish the domain-based name.

The namespace migration was published on November 1, 2026. Both versions of the
older `io.github.allscreenshots/allscreenshots` entry were retired from discovery
because the registry permits an endpoint URL to belong to only one server name.
Their historical metadata is retained. Glama support has been sent the new entry
for review of the existing listing's transition. Client endpoint configurations
do not need to change.

Run the MCP server locally:

```bash
cd mcp_server
export ALLSCREENSHOTS_API_KEY=test-key
python3 server.py
```

Run tests:

```bash
uv run --with "fastmcp>=2.0" --with "httpx>=0.27" --with "pytest>=8" pytest
```

Package the Claude Code and Codex plugin distributions:

```bash
python3 scripts/package_plugins.py
```

Archives are written to `dist/`.

Inspect the Codex marketplace metadata:

```bash
codex plugin marketplace add ./path/to/allscreenshots-plugin
codex
/plugins
```

## License

MIT