README.md•6.94 kB
# TryKitt.ai mcp Server
A FastMCP (Model Context Protocol) server that provides email verification and finding capabilities using the [TryKitt.ai](https://trykitt.ai/) API. This server enables AI assistants to find and verify B2B email addresses with high accuracy and low bounce rates.
## Features
- **Email Verification**: Verify email addresses with advanced SMTP and catchall verification
- **Email Finding**: Find email addresses for individuals using their name and company domain
- **Job Management**: Track and monitor email verification/finding jobs
- **Real-time Processing**: Get immediate results for email operations
- **High Accuracy**: Leverages TryKitt.ai's advanced verification algorithms with <0.1% bounce rate
## Installation
1. Clone this repository:
```bash
git clone https://github.com/avivshafir/trykittai-mcp-server
cd trykittai-mcp-server
```
2. Initialize a new Python environment with uv:
```bash
# Initialize a new uv project (if starting fresh)
uv init
# Or create a virtual environment
uv venv
# Activate the virtual environment
source .venv/bin/activate # On macOS/Linux
```
3. Install dependencies using uv:
```bash
# Using uv (recommended)
uv sync
```
## Setup
1. Get your TryKitt.ai API key:
- Visit [TryKitt.ai](https://trykitt.ai/)
- Sign up for an account
- Navigate to your API settings to get your API key
2. Set your API key as an environment variable:
```bash
export TRYKITT_API_KEY="your_api_key_here"
```
Or create a `.env` file in the project root:
```
TRYKITT_API_KEY=your_api_key_here
```
## Usage
### Running the Server
Start the FastMCP server:
```bash
python server.py
```
The server will start and be available for MCP connections.
### Adding to MCP Clients
To use this server with MCP-compatible clients, you'll need to configure the client to connect to this server.
#### 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": {
"trykittai": {
"command": "python",
"args": ["/path/to/your/trykittai-mcp-server/server.py"],
"env": {
"TRYKITT_API_KEY": "your_api_key_here"
}
}
}
}
```
#### Other MCP Clients
For other MCP-compatible clients, configure them to connect to:
- **Command**: `python`
- **Arguments**: `["/path/to/your/trykittai-mcp-server/server.py"]`
- **Environment Variables**: `TRYKITT_API_KEY=your_api_key_here`
#### Using with uv
If you're using uv, you can also run the server with:
```json
{
"mcpServers": {
"trykittai": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/your/trykittai-mcp-server",
"env": {
"TRYKITT_API_KEY": "your_api_key_here"
}
}
}
}
```
**Note**: Replace `/path/to/your/trykittai-mcp-server` with the actual absolute path to your project directory, and `your_api_key_here` with your actual TryKitt.ai API key.
### Available Tools
#### 1. Email Verification (`verify_email_send`)
Verify if an email address is valid and deliverable.
**Parameters:**
- `email` (required): The email address to verify
- `custom_data` (optional): Custom data to associate with the request
**Example:**
```python
result = await verify_email_send("john.doe@example.com")
```
#### 2. Email Finding (`find_email`)
Find an email address for a person based on their name and company domain.
**Parameters:**
- `full_name` (required): The full name of the person
- `domain` (required): The company domain or website
- `linkedin_url` (optional): LinkedIn profile URL for better accuracy
- `custom_data` (optional): Custom data to associate with the request
**Example:**
```python
result = await find_email(
full_name="John Doe",
domain="example.com",
linkedin_url="https://linkedin.com/in/johndoe"
)
```
#### 3. Job Status (`get_job_status`)
Check the status of a previously submitted job.
**Parameters:**
- `job_id` (required): The ID of the job to check
**Example:**
```python
result = await get_job_status("job_123456")
```
#### 4. List Jobs (`list_jobs`)
List all jobs (Note: This endpoint may have limited availability).
**Example:**
```python
result = await list_jobs()
```
## API Response Format
### Successful Email Verification
```json
{
"id": "job_123456",
"status": "completed",
"result": {
"email": "john.doe@example.com",
"valid": true,
"deliverable": true,
"confidence": 0.95,
"verification_type": "smtp_catchall"
}
}
```
### Successful Email Finding
```json
{
"id": "job_789012",
"status": "completed",
"result": {
"email": "john.doe@example.com",
"confidence": 0.88,
"sources": ["pattern_matching", "web_scraping"]
}
}
```
## Error Handling
The server handles various error scenarios:
- Invalid API keys
- Rate limiting
- Network timeouts
- Invalid email formats
- Domain verification failures
Common error responses:
```json
{
"error": "Invalid API key",
"code": 401
}
```
## Configuration
### Environment Variables
- `TRYKITT_API_KEY`: Your TryKitt.ai API key (required)
### SSL Configuration
The server is configured to work with TryKitt.ai's API endpoints. SSL verification is currently disabled for compatibility.
## Development
### Project Structure
```
trykittai-mcp-server/
├── server.py # Main FastMCP server implementation
├── pyproject.toml # Project dependencies and configuration
├── uv.lock # Dependency lock file
├── README.md # This file
├── LICENSE # MIT License
└── .venv/ # Virtual environment
```
### Dependencies
- `fastmcp`: FastMCP framework for building MCP servers
- `httpx`: Async HTTP client for API requests
- `pydantic`: Data validation and settings management
## About TryKitt.ai
TryKitt.ai is an advanced email verification and finding service that:
- Provides unlimited free email verification for individual users
- Achieves <0.1% bounce rates through advanced verification
- Works 2-5X faster than alternative solutions
- Uses enterprise identity servers for catchall verification
- Detects job changes and validates against real systems
Learn more at [https://trykitt.ai/](https://trykitt.ai/)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Support
For issues related to:
- This MCP server: Open an issue in this repository
- TryKitt.ai API: Contact TryKitt.ai support
- FastMCP framework: Check the FastMCP documentation
## Changelog
### v1.0.0
- Initial release with email verification and finding capabilities
- Job status tracking
- Real-time processing support
- FastMCP integration