# screenshotfreeapi-mcp

MCP server for [ScreenshotFreeAPI](https://screenshotfreeapi.com) — capture websites, render HTML/PDF, and fetch app store listing screenshots from any MCP-compatible AI client (Claude Desktop, Cursor, VS Code Copilot, Cline, Windsurf, etc.).

## Setup

Get an API key from your [ScreenshotFreeAPI dashboard](https://screenshotfreeapi.com/dashboard/api-keys), then add this server to your MCP client's config.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "screenshotfreeapi": {
      "command": "npx",
      "args": ["-y", "screenshotfreeapi-mcp"],
      "env": {
        "SCREENSHOTFREEAPI_KEY": "sfa_your_api_key_here"
      }
    }
  }
}
```

Other MCP clients (Cursor, Cline, Windsurf) use the same `command`/`args`/`env` shape in their own config file — consult your client's docs for the config file location.

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `SCREENSHOTFREEAPI_KEY` | Yes | Your API key (`sfa_...`). Without it, every tool call fails with 401. |
| `SCREENSHOTFREEAPI_BASE_URL` | No | Override the API base URL. Defaults to `https://api.screenshotfreeapi.com`. |

## Tools

| Tool | Description |
|---|---|
| `screenshot_web` | Capture a website screenshot (PNG/JPEG/WebP/PDF), with AI element targeting, full-page, custom viewport, and ad-block options. |
| `screenshot_mobile` | Capture app store listing screenshots (iOS/Android) by app name or bundle ID. |
| `render_html` | Render raw HTML/CSS to an image or PDF. |
| `get_job_status` | Poll the status of a screenshot job. |
| `get_job_result` | Fetch the result (URLs + metadata) of a completed job. |
| `list_jobs` | List recent jobs for the authenticated account. |
| `check_quota` | Check remaining screenshot quota and current plan. |

All capture tools are asynchronous: they enqueue a job and return a `jobId`. Use `get_job_status` to poll, then `get_job_result` once `status` is `completed`.

## Local development

```bash
npm install
npm run dev        # run directly with tsx
npm run build       # compile to dist/ for npx/publish
npm run typecheck
```

## License

MIT