README.md•4.35 kB
# 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.
[](https://github.com/adamanz/exa-websets-mcp)
[](LICENSE)
[](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