FineData MCP Server

MCP (Model Context Protocol) server for FineData web scraping API.

Enables AI agents like Claude, Cursor, and GPT to scrape any website with:

• Antibot Bypass - Cloudflare, DataDome, PerimeterX, and more
• JavaScript Rendering - Full browser rendering with Playwright
• Captcha Solving - reCAPTCHA, hCaptcha, Cloudflare Turnstile, Yandex
• Proxy Rotation - 87K+ datacenter, residential, and mobile proxies
• Smart Retry - Automatic retries with block detection
• Markdown Output - Returns clean Markdown by default (optimized for AI agents)
• AI Extraction - Extract structured data using natural language prompts (Qwen3-32B)

Installation

Using uvx (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run directly with uvx
FINEDATA_API_KEY=fd_xxx uvx finedata-mcp

Using pip

pip install finedata-mcp

# Run
FINEDATA_API_KEY=fd_xxx finedata-mcp

Using npx

npx -y @finedata/mcp-server

Configuration

Cursor IDE

Step 1: Open Cursor Settings → MCP

Or create/edit ~/.cursor/mcp.json:

macOS/Linux:

mkdir -p ~/.cursor && nano ~/.cursor/mcp.json

Windows:

%USERPROFILE%\.cursor\mcp.json

Step 2: Add FineData MCP server:

{
  "mcpServers": {
    "finedata": {
      "command": "uvx",
      "args": ["finedata-mcp"],
      "env": {
        "FINEDATA_API_KEY": "fd_your_api_key_here"
      }
    }
  }
}

Step 3: Restart Cursor

Step 4: Test by asking the agent:

"Scrape https://example.com and show me the title"

Alternative: Using npx (if uv not installed)

{
  "mcpServers": {
    "finedata": {
      "command": "npx",
      "args": ["-y", "@finedata/mcp-server"],
      "env": {
        "FINEDATA_API_KEY": "fd_your_api_key_here"
      }
    }
  }
}

Note: npx requires Python 3.10+ and uv/pipx installed. uvx is recommended.

Claude Desktop

Step 1: Open config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add MCP server:

{
  "mcpServers": {
    "finedata": {
      "command": "uvx",
      "args": ["finedata-mcp"],
      "env": {
        "FINEDATA_API_KEY": "fd_your_api_key_here"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Environment Variables

Available Tools

scrape_url

Scrape content from any web page with antibot bypass.

scrape_url(
  url: "https://example.com",
  formats: ["markdown"],            # Output: markdown, rawHtml, text, links (default: ["markdown"])
  only_main_content: true,          # Extract main content only (default: true)
  extract_prompt: null,             # AI extraction instruction (e.g. "Extract all product prices")
  use_js_render: false,             # Enable Playwright for SPAs
  stealth_antibot: false,           # Stealth mode for Cloudflare, DataDome (+7 tokens)
  stealth_antibot_headful: false,   # Maximum bypass with real browser (+25 tokens)
  stealth_new: false,               # Experimental engine (+15 tokens)
  use_residential: false,           # Use residential proxy
  solve_captcha: false,             # Auto-solve captchas
  timeout: 60                       # Timeout in seconds
)

Note: The MCP server returns Markdown by default (not raw HTML), which is optimized for AI agent consumption.

Token costs:

• Base request: 1 token
• Antibot bypass: +2 tokens
• JS rendering: +5 tokens
• Stealth Antibot: +7 tokens
• Stealth Headful: +25 tokens
• Stealth New: +15 tokens
• Residential proxy: +3 tokens
• Captcha solving: +10 tokens

scrape_async

Submit an async scraping job for long-running requests.

scrape_async(
  url: "https://heavy-site.com",
  use_js_render: true,
  timeout: 120,
  callback_url: "https://your-webhook.com/callback"
)

Returns a job_id for status polling.

get_job_status

Get the status of an async scraping job.

get_job_status(job_id: "550e8400-e29b-41d4-a716-446655440000")

Statuses: pending, processing, completed, failed, cancelled

batch_scrape

Scrape multiple URLs in a single batch (up to 100 URLs).

batch_scrape(
  urls: ["https://example.com/1", "https://example.com/2"],
  use_js_render: false,
  callback_url: "https://your-webhook.com/batch-done"
)

get_usage

Get current API token usage.

get_usage()

Examples

Basic Scraping

Ask Claude or your AI agent:

"Scrape https://example.com and show me the content"

JavaScript Rendered Page

"Scrape https://spa-website.com with JavaScript rendering enabled"

Protected Site with Captcha

"Scrape https://protected-site.com using residential proxy and captcha solving"

AI Data Extraction

"Scrape https://shop.com/products and extract all product names and prices"

Batch Scraping

"Scrape these URLs: https://example.com/1, https://example.com/2, https://example.com/3"

Pricing

FineData uses token-based pricing. Each feature adds tokens:

Get your API key and free trial tokens at finedata.ai.

Troubleshooting

"No module named finedata_mcp"

Install uv and use uvx:

curl -LsSf https://astral.sh/uv/install.sh | sh

"externally-managed-environment" on macOS

This happens with Homebrew Python. Use uvx instead of pip:

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

MCP server not appearing in Cursor

1. Check ~/.cursor/mcp.json syntax (valid JSON)
2. Ensure FINEDATA_API_KEY is set
3. Restart Cursor completely
4. Check Cursor Output → MCP for errors

Support

• Documentation: https://finedata.ai/docs
• Email: support@finedata.ai
• Issues: https://github.com/quality-network/finedata-mcp/issues

License

MIT