Metadata-Version: 2.4
Name: evomi-mcp
Version: 1.0.0
Summary: MCP server for Evomi web scraping API
Project-URL: Homepage, https://evomi.com
Project-URL: Documentation, https://docs.evomi.com
Author-email: Evomi <support@evomi.com>
Keywords: ai,claude,evomi,mcp,model context protocol,scraper,web scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Evomi MCP Server

A Model Context Protocol (MCP) server for the Evomi web scraping API. Use this to give AI assistants like Claude the ability to scrape websites, crawl pages, extract data, and more.

## Features

- **Single Page Scraping** - Scrape any URL with automatic JavaScript detection
- **Website Crawling** - Multi-page crawling with depth control
- **URL Discovery** - Find URLs via sitemaps, CommonCrawl, or in-site crawling
- **Domain Search** - Find domains by searching the web
- **AI-Powered Extraction** - Use AI to extract structured data from pages
- **Conversational Agent** - Natural language interface for scraping tasks
- **Config Management** - Save and reuse scraping configurations
- **Schema Management** - Define and test extraction schemas
- **Storage Configuration** - Manage cloud storage for scraped data
- **Scheduled Jobs** - Automate scraping on a schedule

## Installation

### Using pip

```bash
pip install evomi-mcp
```

### From Source

```bash
cd evomi-mcp
pip install -e .
```

## Configuration

Set your Evomi API key as an environment variable:

```bash
export EVOMI_API_KEY="your-api-key-here"
```

Optionally, you can also set a custom base URL:

```bash
export EVOMI_BASE_URL="https://scrape.evomi.com"  # default
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "evomi": {
      "command": "evomi-mcp",
      "env": {
        "EVOMI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Or if installed from source:

```json
{
  "mcpServers": {
    "evomi": {
      "command": "python",
      "args": ["-m", "evomi_mcp.server"],
      "env": {
        "EVOMI_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools (25 Total)

### Scraping Operations (6 tools)

| Tool | Description |
|------|-------------|
| `scrape_url` | Scrape a single URL with configurable options |
| `crawl_website` | Crawl a website to discover and scrape multiple pages |
| `map_website` | Discover URLs from a website |
| `search_domains` | Find domains by searching the web |
| `agent_request` | AI-powered conversational scraping assistant |
| `get_task_status` | Check the status of an async task |

### Config Management (6 tools)

| Tool | Description |
|------|-------------|
| `list_configs` | List all saved scrape configurations |
| `create_config` | Create a new scrape configuration |
| `get_config` | Get a saved scrape configuration by ID |
| `update_config` | Update an existing scrape configuration |
| `delete_config` | Delete a scrape configuration |
| `generate_config` | Generate a scrape config from natural language using AI |

### Schema Management (6 tools)

| Tool | Description |
|------|-------------|
| `list_schemas` | List all saved extraction schemas |
| `create_schema` | Create a new extraction schema |
| `get_schema` | Get a saved extraction schema by ID |
| `update_schema` | Update an existing extraction schema |
| `delete_schema` | Delete an extraction schema |
| `get_schema_status` | Get the test status of an extraction schema |

### Storage Management (4 tools)

| Tool | Description |
|------|-------------|
| `list_storage_configs` | List all storage configurations |
| `create_storage_config` | Create a new storage configuration |
| `update_storage_config` | Update an existing storage configuration |
| `delete_storage_config` | Delete a storage configuration |

### Schedule Management (7 tools)

| Tool | Description |
|------|-------------|
| `list_schedules` | List all scheduled scrape jobs |
| `create_schedule` | Create a new scheduled scrape job |
| `get_schedule` | Get a scheduled job by ID |
| `update_schedule` | Update an existing scheduled job |
| `delete_schedule` | Delete a scheduled job |
| `toggle_schedule` | Toggle a scheduled job active/inactive |
| `list_schedule_runs` | Get execution history for a scheduled job |

### Account (1 tool)

| Tool | Description |
|------|-------------|
| `get_account_info` | Get account information including credit balance |

## Tool Examples

### Scraping

```json
// Basic scrape
{"url": "https://example.com"}

// AI extraction
{"url": "https://example.com/products", "ai_enhance": true, "ai_prompt": "Extract product names and prices"}

// Browser mode with actions
{"url": "https://example.com", "mode": "browser", "js_instructions": [{"click": ".accept-cookies"}, {"wait": 1000}]}
```

### Crawling

```json
// Basic crawl
{"domain": "example.com", "max_urls": 50}

// With URL filter
{"domain": "example.com", "url_pattern": "/products/", "depth": 3}
```

### Domain Search

```json
// Find domains
{"query": "best e-commerce sites for electronics", "max_urls": 20, "region": "us-en"}
```

### Config Management

```json
// Create config
{"name": "Product Scraper", "config": {"mode": "browser", "output": "markdown"}}

// Generate config with AI
{"name": "Amazon Scraper", "prompt": "Scrape product title, price, and reviews from Amazon"}
```

### Scheduling

```json
// Create daily schedule
{"name": "Daily Prices", "config_id": "cfg_abc123", "interval_minutes": 1440, "start_time": "09:00"}
```

## Pricing & Credits

All operations consume credits based on:

- **Base cost**: 1 credit per request
- **Browser mode**: 5x multiplier
- **Residential proxy**: 2x multiplier
- **AI enhancement**: +30 credits
- **Screenshot/PDF**: +1 credit each

Credit information is returned in each response.

## Development

### Setup

```bash
cd evomi-mcp
pip install -e ".[dev]"
```

### Running the Server Directly

```bash
evomi-mcp
# or
python -m evomi_mcp.server
```

## Links

- [Evomi Website](https://evomi.com)
- [Evomi Dashboard](https://dashboard.evomi.com)
- [API Documentation](https://docs.evomi.com)

## License

MIT License - see LICENSE file for details.