README.md6.05 kB
# RevenueBase MCP Server
A Model Context Protocol (MCP) server that provides access to RevenueBase's industry-leading email verification API. This server enables AI assistants and applications to verify business emails, including catch-all and firewall-protected domains, with over 99% accuracy.
## Features
- **Real-time Email Verification**: Verify individual email addresses instantly
- **Batch Email Processing**: Submit and process large email lists
- **Process Management**: Monitor, cancel, and track batch processing jobs
- **Credit Management**: Check remaining API credits
- **API Key Management**: Generate new API keys
- **High Accuracy**: Over 99% accuracy for B2B email verification
- **Catch-All Domain Support**: Verify catch-all email domains that other tools can't handle
- **Firewall Navigation**: Bypass email firewalls like Mimecast and Barracuda
## About RevenueBase
RevenueBase provides industry-leading email verification services specifically built for B2B data providers. With the ability to verify catch-all and firewall-protected domains, RevenueBase ensures maximum accuracy where other services fall short.
Learn more about RevenueBase's email verification services at: [https://revenuebase.ai/email-list-cleaning/](https://revenuebase.ai/email-list-cleaning/)
## Installation
1. Clone this repository:
```bash
git clone https://github.com/avivshafir/revenuebase-mcp-server
cd revenuebase-mcp-server
```
2. Install dependencies using uv:
```bash
uv sync
```
3. Set up your RevenueBase API key:
```bash
export REVENUEBASE_API_KEY="your_api_key_here"
```
## Usage
### Running the Server
```bash
python server.py
```
The server will start and be available for MCP connections.
### Using with MCP Clients
#### Claude Desktop
To use this server with 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`
```json
{
"mcpServers": {
"revenuebase": {
"command": "uv",
"args": ["--directory", "/path/to/revenuebase-mcp-server", "run", "python", "server.py"],
"env": {
"REVENUEBASE_API_KEY": "your_api_key_here"
}
}
}
}
```
Replace `/path/to/revenuebase-mcp-server` with the actual path to your cloned repository and `your_api_key_here` with your actual RevenueBase API key.
#### Other MCP Clients
For other MCP clients, you can connect to the server using the stdio transport. The server runs as a standard MCP server and accepts connections on stdin/stdout.
Example using the MCP Python SDK:
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
server_params = StdioServerParameters(
command="python",
args=["server.py"],
env={"REVENUEBASE_API_KEY": "your_api_key_here"}
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the connection
await session.initialize()
# List available tools
tools = await session.list_tools()
print("Available tools:", [tool.name for tool in tools.tools])
# Call a tool
result = await session.call_tool("real_time_email_verification", {
"email": "test@example.com"
})
print("Verification result:", result)
```
### Available Tools
#### 1. Real-time Email Verification
Verify a single email address instantly.
**Parameters:**
- `email` (string): The email address to verify
**Example:**
```python
real_time_email_verification("user@example.com")
```
#### 2. Batch Email Submission
Submit a file reference for batch email processing.
**Parameters:**
- `filename` (string): The filename reference for batch processing
**Example:**
```python
batch_email_submission("email_list.csv")
```
#### 3. Batch Process Status
Check the status of a batch email processing job.
**Parameters:**
- `process_id` (int): The ID of the batch processing job
**Example:**
```python
batch_process_email_status(12345)
```
#### 4. Queued Processes
List all queued email batch processing jobs.
**Example:**
```python
queued_process()
```
#### 5. Cancel Process
Cancel an ongoing or queued batch email processing job.
**Parameters:**
- `process_id` (int): The ID of the process to cancel
**Example:**
```python
cancel_process(12345)
```
#### 6. Get Credits
Retrieve the number of remaining credits for your account.
**Example:**
```python
get_credits()
```
#### 7. Generate New API Key
Generate and return a new API key.
**Example:**
```python
new_api_key()
```
## Configuration
### Environment Variables
- `REVENUEBASE_API_KEY`: Your RevenueBase API key (required)
### API Endpoints
The server connects to the following RevenueBase API endpoints:
- `https://api.revenuebase.ai/v1/process-email` - Real-time email verification
- `https://api.revenuebase.ai/v1/batch-process-email` - Batch email submission
- `https://api.revenuebase.ai/v1/batch-process-email-status` - Batch status check
- `https://api.revenuebase.ai/v1/queued-process` - List queued processes
- `https://api.revenuebase.ai/v1/cancel-process` - Cancel process
- `https://api.revenuebase.ai/v1/credits` - Get credits
- `https://api.revenuebase.ai/v1/new-api-key` - Generate new API key
## Error Handling
All tools include proper error handling and will raise `RuntimeError` if the API key is not configured. HTTP errors from the RevenueBase API are automatically raised using `requests.raise_for_status()`.
## Requirements
- Python 3.7+
- fastmcp
- requests
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For RevenueBase API support and documentation, visit:
- [RevenueBase Email Verification](https://revenuebase.ai/email-list-cleaning/)
- [RevenueBase API Documentation](https://revenuebase.ai/api-documentation)
For issues with this MCP server, please open an issue in this repository.