snapapi-mcp

MCP (Model Context Protocol) server for SnapAPI — take screenshots, scrape web pages, extract content, generate PDFs, record videos, and analyze pages directly from AI tools like Claude Desktop, Cursor, Windsurf, Cline, and Zed.

What is this?

This package runs a local MCP server that connects your AI assistant to the SnapAPI web capture API. Once configured, your AI can:

• Take screenshots of any URL (full page, mobile, dark mode, element selection, device emulation)
• Scrape web pages and get clean text, HTML, or link lists using a real browser
• Extract content optimized for LLM consumption (Markdown, article, metadata, structured data)
• Generate PDFs from URLs or HTML
• Record videos of browser sessions with optional interaction scenarios
• Analyze pages with AI (extract + analyze in one call)
• Check your usage quota and account stats

Prerequisites

• Node.js 18 or later
• A SnapAPI API key — get one at snapapi.pics/dashboard.html

Quick Start

Claude Code (CLI)

The fastest way — one command:

claude mcp add snapapi -- npx -y snapapi-mcp

Then set your API key:

# Option 1: Export in your shell profile (~/.zshrc or ~/.bashrc)
export SNAPAPI_API_KEY="sk_live_your_key_here"

# Option 2: Add to .claude/settings.json

Or add directly to your project's .mcp.json:

{
  "mcpServers": {
    "snapapi": {
      "command": "npx",
      "args": ["-y", "snapapi-mcp"],
      "env": {
        "SNAPAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "snapapi": {
      "command": "npx",
      "args": ["-y", "snapapi-mcp"],
      "env": {
        "SNAPAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "snapapi": {
      "command": "npx",
      "args": ["-y", "snapapi-mcp"],
      "env": {
        "SNAPAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "snapapi": {
      "command": "npx",
      "args": ["-y", "snapapi-mcp"],
      "env": {
        "SNAPAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cline (VS Code)

Open Cline settings → MCP Servers → Add Server:

• Command: npx
• Args: -y snapapi-mcp
• Environment: SNAPAPI_API_KEY=sk_live_your_key_here

VS Code (native MCP support)

Add to .vscode/mcp.json in your workspace (or your user settings):

{
  "servers": {
    "snapapi": {
      "command": "npx",
      "args": ["-y", "snapapi-mcp"],
      "env": {
        "SNAPAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "snapapi": {
      "command": {
        "path": "npx",
        "args": ["-y", "snapapi-mcp"],
        "env": {
          "SNAPAPI_API_KEY": "sk_live_your_key_here"
        }
      }
    }
  }
}

Automated Installer

Run the included helper script:

# For Claude Desktop
./install-mcp.sh claude

# For Cursor
./install-mcp.sh cursor

# For Windsurf
./install-mcp.sh windsurf

Available Tools

ping

Verify that SnapAPI is reachable and your API key is valid. No parameters required.

Example prompt: "Ping SnapAPI to check it's working"

screenshot

Take a screenshot of any URL with extensive customization.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | * | URL to capture | | html | string | * | Raw HTML to render (alternative to url) | | markdown | string | * | Markdown to render (alternative to url) | | format | string | no | png, jpeg, webp, or avif (default: png) | | quality | number | no | 1–100 for jpeg/webp (default: 80) | | width | number | no | Viewport width (default: 1280) | | height | number | no | Viewport height (default: 800) | | fullPage | boolean | no | Capture full scrollable page | | selector | string | no | CSS selector for element capture | | delay | number | no | Wait ms after page load before capture | | waitUntil | string | no | load, domcontentloaded, or networkidle | | darkMode | boolean | no | Dark color scheme | | blockAds | boolean | no | Block ad networks | | blockCookieBanners | boolean | no | Block cookie popups | | css | string | no | Custom CSS to inject | | javascript | string | no | Custom JS to execute | | device | string | no | Device preset (e.g. iphone-15-pro) — use list_devices to see all | | hideSelectors | string[] | no | Elements to hide before capture |

*At least one of url, html, or markdown must be provided.

Example prompts:

• "Take a screenshot of https://example.com in dark mode"
• "Screenshot https://github.com on an iPhone 15 Pro"
• "Capture a full-page screenshot of https://news.ycombinator.com with ads blocked"
• "Render this HTML as a screenshot: <h1>Hello</h1>"

scrape

Scrape web page content using a real browser (JavaScript-rendered pages work).

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | yes | URL to scrape | | type | string | no | text (Markdown), html, or links (default: text) | | pages | number | no | Pages to follow, 1–10 (default: 1) | | waitMs | number | no | Extra wait time in ms after page load | | blockResources | boolean | no | Block images/media/fonts to speed up | | locale | string | no | Browser locale (e.g. en-US) | | premiumProxy | boolean | no | Use residential proxy to bypass blocks |

Example prompts:

• "Scrape the text content from https://example.com/blog"
• "Get all links from https://news.ycombinator.com"
• "Scrape https://example.com/pricing as HTML"

extract

Extract clean, structured content optimized for LLMs.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | yes | URL to extract from | | type | string | no | markdown, text, html, article, links, images, metadata, or structured (default: markdown) | | selector | string | no | Scope extraction to a CSS element | | waitFor | string | no | Wait for CSS selector before extracting | | maxLength | number | no | Max character length | | cleanOutput | boolean | no | Remove noise (default: true) | | blockAds | boolean | no | Block ad networks | | blockCookieBanners | boolean | no | Block cookie popups | | fields | object | no | Custom field extraction map |

Example prompts:

• "Extract the article content from https://example.com/post as markdown"
• "Get the metadata (title, description, OG image) from https://example.com"
• "Extract price and rating from https://example.com/product"

pdf

Generate a PDF from a URL or HTML.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | * | URL to convert to PDF | | html | string | * | HTML to convert to PDF (alternative to url) | | pdfOptions.pageSize | string | no | a4, a3, a5, letter, legal, tabloid (default: a4) | | pdfOptions.landscape | boolean | no | Landscape orientation | | pdfOptions.printBackground | boolean | no | Include background graphics | | pdfOptions.scale | number | no | Scale factor 0.1–2 | | pdfOptions.marginTop | string | no | Top margin, e.g. 1cm | | pdfOptions.marginBottom | string | no | Bottom margin | | pdfOptions.marginLeft | string | no | Left margin | | pdfOptions.marginRight | string | no | Right margin | | delay | number | no | Wait ms after page load | | waitUntil | string | no | load, domcontentloaded, or networkidle |

*At least one of url or html must be provided.

Example prompts:

• "Generate a PDF of https://example.com/report in landscape A4"
• "Convert this HTML to a PDF with 2cm margins"

analyze

Extract content from a URL and analyze it with an AI model in one call.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | yes | URL to analyze | | prompt | string | yes | Analysis instruction for the AI | | extractType | string | no | markdown, text, article, or structured (default: article) | | maxLength | number | no | Max characters of content to pass to AI (default: 20000) |

Example prompts:

• "Analyze https://example.com/article — what are the main arguments?"
• "Extract all product specs from https://example.com/product"
• "What is the sentiment of this news article: https://example.com/news"

video

Record a browser session as a video (WebM).

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | url | string | yes | URL to record | | duration | number | no | Recording duration in seconds, 1–60 (default: 5) | | width | number | no | Viewport width (default: 1280) | | height | number | no | Viewport height (default: 800) | | scenario | string | no | JavaScript to run during recording (scroll, click, etc.) | | delay | number | no | Wait ms before starting recording | | waitUntil | string | no | load, domcontentloaded, or networkidle | | darkMode | boolean | no | Dark color scheme | | blockAds | boolean | no | Block ad networks | | blockCookieBanners | boolean | no | Block cookie popups | | device | string | no | Device preset — use list_devices to see all |

Example prompts:

• "Record a 10-second video of https://example.com scrolling down"
• "Record https://example.com on an iPhone 15 Pro"

get_usage

Check your SnapAPI quota and monthly statistics. No parameters required.

Example prompts:

• "How many SnapAPI requests do I have left this month?"
• "Show me my SnapAPI usage"

list_devices

List all available device presets for screenshot and video emulation. No parameters required.

Example prompt: "What device presets are available for screenshots?"

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SNAPAPI_API_KEY | Yes | Your SnapAPI API key (sk_live_...) | | SNAPAPI_BASE_URL | No | API base URL (default: https://api.snapapi.pics) |

Development

# Clone the repo
git clone https://github.com/Sleywill/snapapi-mcp.git
cd snapapi-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally (reads MCP protocol from stdin)
SNAPAPI_API_KEY=sk_live_your_key node dist/index.js

Troubleshooting

"SNAPAPI_API_KEY environment variable is required" Make sure the env block in your MCP config includes your API key. Check it starts with sk_live_.

Tools not appearing in Claude Desktop Restart Claude Desktop after saving the config. Check MCP logs at:

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\mcp*.log

npx takes too long on first run Use "args": ["-y", "snapapi-mcp"] — the -y flag auto-confirms the install prompt without interaction.

screenshot / scrape returns an error

• Verify your API key is valid at snapapi.pics/dashboard.html/dashboard
• Check your remaining quota with the get_usage tool
• For JavaScript-heavy pages, try adding "waitUntil": "networkidle" and a "delay" value

analyze tool returns an error The analyze endpoint requires Anthropic API credits on the SnapAPI backend. Use the extract tool as a fallback to fetch the page content and analyze it yourself.

License

MIT