# Exa Websets MCP Server

A Model Context Protocol (MCP) server for interacting with [Exa's Websets API](https://docs.exa.ai/reference/websets). This server allows you to create and manage websets for AI-powered web search and data collection.

[![GitHub](https://img.shields.io/badge/GitHub-exa--websets--mcp-blue?logo=github)](https://github.com/adamanz/exa-websets-mcp)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)

## Features

- **Create Websets**: Create new websets with customizable search queries
- **Manage Websets**: Get information about existing websets and list all websets
- **Predefined Templates**: Quick creation of common webset types (marketing agencies, tech companies)
- **Full API Support**: Complete integration with Exa's webset creation parameters

## Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Set your Exa API key as an environment variable:
   ```bash
   export EXA_API_KEY="your-exa-api-key-here"
   ```

## Usage

### Running the Server

```bash
python server.py
```

By default, the server runs using STDIO transport for local tools. For web deployments, you can specify HTTP transport:

```bash
python server.py --transport http --port 8000
```

### Available Tools

#### `create_webset`
Create a new webset with custom search parameters.

**Parameters:**
- `query` (required): Natural language search query
- `count`: Number of items to find (default: 10)
- `entity`: Entity type (company, person, article, research_paper)
- `external_id`: External identifier for easier reference
- `criteria`: List of criteria descriptions for evaluation
- `recall`: Whether to provide recall estimates
- `metadata`: Key-value metadata pairs

**Example:**
```python
create_webset(
    query="AI startups in Europe that raised Series A funding in 2024",
    count=15,
    entity="company",
    external_id="ai-startups-europe-series-a"
)
```

#### `get_webset`
Get information about a specific webset.

**Parameters:**
- `webset_id` (required): The unique identifier for the webset

#### `list_websets`
List all websets in your account.

#### `create_marketing_agencies_webset`
Quick template for creating marketing agency websets.

**Parameters:**
- `location`: Geographic location (default: "US")
- `focus`: Focus area or specialization (default: "consumer products")
- `count`: Number of agencies to find (default: 10)

#### `create_tech_companies_webset`
Quick template for creating tech company websets.

**Parameters:**
- `location`: Geographic location (default: "San Francisco")
- `stage`: Company stage (e.g., "startup", "Series A", "public")
- `count`: Number of companies to find (default: 10)

## Adding to Claude Desktop

To use this server with Claude Desktop, add it to your configuration file:

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

```json
{
  "mcpServers": {
    "exa-websets": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/exa-websets-mcp/server.py"],
      "env": {
        "EXA_API_KEY": "your-exa-api-key-here"
      }
    }
  }
}
```

## Testing with MCP Inspector

You can test this server using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

1. Start the inspector:
   ```bash
   npx @modelcontextprotocol/inspector
   ```

2. Connect to your server using the STDIO transport with the path to your `server.py` file.

## Configuration

The server uses the following environment variables:

- `EXA_API_KEY`: Your Exa API key (required)

## API Reference

This server implements the Exa Websets API endpoints:

- `POST /v0/websets` - Create a webset
- `GET /v0/websets/{id}` - Get a webset
- `GET /v0/websets` - List websets

For full API documentation, see [Exa's API Reference](https://docs.exa.ai/reference/websets).

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is open source and available under the MIT License.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
- Uses [Exa's Websets API](https://exa.ai/) for AI-powered web search