MCP Integration - WhizoAI API Documentation

Overview

WhizoAI provides a Model Context Protocol (MCP) server that enables seamless integration with Claude Desktop and other MCP-compatible AI tools. This allows you to use WhizoAI’s web scraping, crawling, and data extraction capabilities directly within your AI assistant conversations.

MCP Server Package: whizoai-mcp - Published on npm

Prerequisites

Node.js 18 or higher
WhizoAI API key (Get your API key)
Claude Desktop or another MCP-compatible tool

Quick Setup

1. Get Your API Key

Log in to your WhizoAI Dashboard
Navigate to API Keys
Copy your existing API key or create a new one

2. Configure Claude Desktop

Add the following configuration to your Claude Desktop config file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whizoai": {
      "command": "npx",
      "args": ["-y", "whizoai-mcp"],
      "env": {
        "WHIZOAI_API_KEY": "wai_your_api_key_here"
      }
    }
  }
}

Replace wai_your_api_key_here with your actual WhizoAI API key from the dashboard.

3. Restart Claude Desktop

After saving the configuration file, restart Claude Desktop to load the MCP server.

4. Verify Installation

In Claude Desktop, you should now see the WhizoAI MCP server listed in the available tools. You can verify by asking:

Can you scrape https://example.com for me?

Available Tools

The WhizoAI MCP server provides 10 powerful tools:

Core Scraping Tools

whizoai_scrape

Scrape single or multiple webpages (1-100 URLs) with native multi-URL support and automatic parallelization

whizoai_crawl

Crawl multiple pages from a website with depth and page limits

whizoai_extract

AI-powered data extraction using structured schemas

whizoai_search

Perform web searches and get scraped content from results

whizoai_screenshot

Capture high-quality screenshots with custom viewport sizes and mobile/desktop modes

Job Management Tools

whizoai_job_status

Check the status of a running job

whizoai_list_jobs

List recent jobs with filtering options

whizoai_cancel_job

Cancel a running or pending job

Account Tools

whizoai_check_credits

Check your remaining credit balance

whizoai_map

Discover URLs from a website (map structure)

Usage Examples

Example 1: Simple Web Scraping

User: Can you scrape the content from https://news.ycombinator.com and summarize the top stories?

Claude: I'll scrape Hacker News for you and summarize the top stories.
[Uses whizoai_scrape tool]
[Provides summary based on scraped content]

Example 2: Multi-URL Scraping

New in v2.2.1: Native multi-URL support directly in the scrape tool! Process 1-100 URLs in a single request with automatic parallelization.

User: Scrape these 3 URLs and compare their pricing pages:
- https://example.com/pricing
- https://competitor1.com/pricing
- https://competitor2.com/pricing

Claude: I'll scrape all 3 pricing pages simultaneously for you.
[Uses whizoai_scrape tool with urls array]
[Returns jobId for tracking]
[Later retrieves results with whizoai_get_job tool]
[Compares pricing information from all 3 sites]

Multi-URL Features:

Process 1-100 URLs in a single request
Automatic parallelization for faster results
Background job processing with progress tracking
Use whizoai_get_job tool to monitor progress and retrieve results
All scraping options work with multi-URL (screenshots, PDFs, etc.)

Example 3: Multi-Page Crawling

User: Crawl https://docs.example.com and create a summary of their API documentation

Claude: I'll crawl the documentation site to gather all API-related pages.
[Uses whizoai_crawl tool]
[Analyzes crawled pages and creates comprehensive summary]

Example 3: Structured Data Extraction

User: Extract all product information from https://example.com/products including names, prices, and descriptions

Claude: I'll extract the structured product data from that page.
[Uses whizoai_extract tool with appropriate schema]
[Returns formatted product data]

Example 4: Web Search with Content

User: Search for recent articles about AI in healthcare and summarize the findings

Claude: I'll search for recent AI healthcare articles and analyze their content.
[Uses whizoai_search tool]
[Provides synthesized summary from multiple sources]

Example 5: Screenshot Capture

User: Take a mobile screenshot of https://example.com

Claude: I'll capture a mobile screenshot of that page for you.
[Uses whizoai_screenshot tool with mobile: true, fullPage: true]
[Returns screenshot URL]

Here's the mobile screenshot: [screenshot URL]

Screenshot Options:

Mobile mode: Emulate mobile device with appropriate viewport and user agent
Desktop mode: Standard desktop viewport (default)
Custom viewport: Specify exact width and height (320-3840 x 240-2160)
Full page: Capture entire page or just visible viewport
Wait time: Wait for dynamic content to load before capturing

Configuration Options

Custom API URL

If you’re using a self-hosted WhizoAI instance or testing locally, you can specify a custom API URL:

{
  "mcpServers": {
    "whizoai": {
      "command": "npx",
      "args": ["-y", "whizoai-mcp"],
      "env": {
        "WHIZOAI_API_KEY": "wai_your_api_key_here",
        "WHIZOAI_API_URL": "http://localhost:8080"
      }
    }
  }
}

Multiple Environments

You can configure multiple WhizoAI MCP servers for different environments:

{
  "mcpServers": {
    "whizoai-prod": {
      "command": "npx",
      "args": ["-y", "whizoai-mcp"],
      "env": {
        "WHIZOAI_API_KEY": "wai_production_key"
      }
    },
    "whizoai-dev": {
      "command": "npx",
      "args": ["-y", "whizoai-mcp"],
      "env": {
        "WHIZOAI_API_KEY": "wai_development_key",
        "WHIZOAI_API_URL": "http://localhost:8080"
      }
    }
  }
}

Features

✅ 10 Powerful Tools - Comprehensive web scraping and data extraction capabilities ✅ Screenshot Capture - High-quality screenshots with mobile/desktop modes ✅ Real-time Job Status - Monitor long-running scraping jobs ✅ Credit Management - Check your credit balance directly from Claude ✅ Easy Installation - One-line setup with npx ✅ Automatic Updates - Always uses the latest version with -y flag ✅ Secure - API key-based authentication

Credit Usage

MCP tool calls consume credits from your WhizoAI account based on the operation:

Tool	Base Cost	Additional
`whizoai_scrape`	1 credit	+1 for screenshot, +1 for PDF
`whizoai_screenshot`	1 credit	Per screenshot captured
`whizoai_crawl`	1 credit/page	Depends on pages crawled
`whizoai_extract`	3-6 credits/page	Based on AI model used
`whizoai_search`	1 credit	Per search query
`whizoai_map`	1 credit	Per discovery request
Other tools	Free	No credit cost

Monitor your credit usage from the Dashboard or use the whizoai_check_credits tool in Claude.

Troubleshooting

MCP Server Not Loading

Check Configuration Path: Ensure you’re editing the correct config file
Validate JSON: Use a JSON validator to check for syntax errors
Restart Claude: Completely quit and restart Claude Desktop
Check Logs: View MCP server logs in Claude Desktop’s developer console

API Key Issues

Verify API Key: Ensure your API key is active in the Dashboard
Check Format: API keys should start with wai_
Permissions: Ensure the key has appropriate permissions

Connection Errors

Network: Verify you have internet connectivity
Firewall: Check if firewall is blocking npx or Node.js
API Status: Check status.whizo.ai for service health

Best Practices

Optimize Credit Usage

Use onlyMainContent: true for scraping to reduce costs
Limit crawl depth and pages to only what you need
Use whizoai_map to discover URLs before crawling
Cache results when possible

Handle Rate Limits

Monitor your plan’s rate limits in the dashboard
Use batch operations instead of sequential individual requests
Implement exponential backoff for retries
Upgrade your plan if you consistently hit limits

Secure Your API Key

Never commit API keys to version control
Rotate API keys periodically
Use separate keys for development and production
Revoke unused or compromised keys immediately

Advanced Usage

Using with Other MCP Clients

While this guide focuses on Claude Desktop, the WhizoAI MCP server works with any MCP-compatible client:

# Run directly with node
npx -y whizoai-mcp

# Or install globally
npm install -g whizoai-mcp
whizoai-mcp

Local Development

For local development and testing:

{
  "mcpServers": {
    "whizoai-local": {
      "command": "npx",
      "args": ["-y", "whizoai-mcp"],
      "env": {
        "WHIZOAI_API_KEY": "wai_test_key",
        "WHIZOAI_API_URL": "http://localhost:8080",
        "DEBUG": "true"
      }
    }
  }
}

Support

Need help with the MCP integration?

Documentation: docs.whizo.ai
Email Support: [email protected]
GitHub Issues: github.com/whizoai
Status Page: status.whizo.ai

API Keys

Learn how to create and manage API keys

JavaScript SDK

Use WhizoAI in your Node.js applications

Python SDK

Use WhizoAI in your Python projects

API Reference

Explore all available API endpoints

Getting Started

Guides

Integrations

​Overview

​Prerequisites

​Quick Setup

​1. Get Your API Key

​2. Configure Claude Desktop

​3. Restart Claude Desktop

​4. Verify Installation

​Available Tools

​Core Scraping Tools

whizoai_scrape

whizoai_crawl

whizoai_extract

whizoai_search

whizoai_screenshot

​Job Management Tools

whizoai_job_status

whizoai_list_jobs

whizoai_cancel_job

​Account Tools

whizoai_check_credits

whizoai_map

​Usage Examples

​Example 1: Simple Web Scraping

​Example 2: Multi-URL Scraping

​Example 3: Multi-Page Crawling

​Example 3: Structured Data Extraction

​Example 4: Web Search with Content

​Example 5: Screenshot Capture

​Configuration Options

​Custom API URL

​Multiple Environments

​Features

​Credit Usage

​Troubleshooting

​MCP Server Not Loading

​API Key Issues

​Connection Errors

​Best Practices

​Advanced Usage

​Using with Other MCP Clients

​Local Development

​Support

​Related Resources

API Keys

JavaScript SDK

Python SDK

API Reference

Overview

Prerequisites

Quick Setup

1. Get Your API Key

2. Configure Claude Desktop

3. Restart Claude Desktop

4. Verify Installation

Available Tools

Core Scraping Tools

Job Management Tools

Account Tools

Usage Examples

Example 1: Simple Web Scraping

Example 2: Multi-URL Scraping

Example 3: Multi-Page Crawling

Example 3: Structured Data Extraction

Example 4: Web Search with Content

Example 5: Screenshot Capture

Configuration Options

Custom API URL

Multiple Environments

Features

Credit Usage

Troubleshooting

MCP Server Not Loading

API Key Issues

Connection Errors

Best Practices

Advanced Usage

Using with Other MCP Clients

Local Development

Support

Related Resources