# MCP AbuseIPDB Server
An MCP (Model Context Protocol) server that provides threat intelligence lookups against the AbuseIPDB database. This server enables any MCP-capable client to perform IP reputation checks, CIDR block analysis, and access curated blacklists with intelligent caching and rate limiting.
## Features
- **IP Reputation Checks**: Single IP address lookups with detailed abuse data
- **CIDR Block Analysis**: Check entire network ranges for malicious activity
- **Blacklist Access**: Retrieve current AbuseIPDB blacklist with configurable confidence levels
- **Bulk Operations**: Check multiple IP addresses efficiently
- **Log Enrichment**: Extract and analyze IP addresses from log lines
- **Intelligent Caching**: SQLite-based caching with TTL to minimize API usage
- **Rate Limiting**: Built-in quota management for AbuseIPDB API limits
- **Security Focused**: Input validation, private IP filtering, and secure defaults
## Quick Start
### Prerequisites
- Python 3.11 or higher
- AbuseIPDB API key (get one at [abuseipdb.com](https://www.abuseipdb.com/api))
### Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd AbuseIPDB-MCP
```
2. Install the package:
```bash
pip install -e .
```
3. Set up your environment:
```bash
cp .env.example .env
# Edit .env and add your ABUSEIPDB_API_KEY
```
4. Run the server:
```bash
python -m mcp_abuseipdb.server
```
### MCP Client Configuration
#### Option 1: Using the Enhanced Startup Script (Recommended)
Add to your MCP client configuration (e.g., `mcp.json`):
```json
{
"mcpServers": {
"mcp-abuseipdb": {
"command": "python",
"args": ["scripts/start_mcp_server.py"],
"cwd": "/path/to/AbuseIPDB-MCP",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
#### Option 2: Direct Module Execution
```json
{
"mcpServers": {
"mcp-abuseipdb": {
"command": "python",
"args": ["-m", "mcp_abuseipdb.server"],
"cwd": "/path/to/AbuseIPDB-MCP",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}
```
**Important Notes:**
- Replace `your_api_key_here` with your actual AbuseIPDB API key
- Update `/path/to/AbuseIPDB-MCP` to the actual path where you cloned this repository
- The enhanced startup script (Option 1) provides better error diagnostics
- Ensure your API key is valid and not expired on the AbuseIPDB website
## Available Tools
### `check_ip`
Check the reputation of a single IP address.
**Parameters:**
- `ip_address` (required): IP address to check
- `max_age_days` (optional): Maximum age of reports (default: 30)
- `verbose` (optional): Include detailed reports (default: false)
- `threshold` (optional): Confidence threshold for flagging (default: 75)
### `check_block`
Check the reputation of a CIDR network block.
**Parameters:**
- `network` (required): CIDR network (e.g., "192.168.1.0/24")
- `max_age_days` (optional): Maximum age of reports (default: 30)
### `get_blacklist`
Retrieve the AbuseIPDB blacklist.
**Parameters:**
- `confidence_minimum` (optional): Minimum confidence level (default: 90)
- `limit` (optional): Maximum entries to retrieve
### `bulk_check`
Check multiple IP addresses efficiently.
**Parameters:**
- `ip_addresses` (required): List of IP addresses
- `max_age_days` (optional): Maximum age of reports (default: 30)
- `threshold` (optional): Confidence threshold for flagging (default: 75)
### `enrich_log_line`
Extract and analyze IP addresses from log entries.
**Parameters:**
- `log_line` (required): Log line containing IP addresses
- `threshold` (optional): Confidence threshold for flagging (default: 75)
- `max_age_days` (optional): Maximum age of reports (default: 30)
## Available Resources
### `cache://info`
Get current cache statistics and rate limiter status.
### `doc://usage`
Complete API usage documentation and examples.
## Available Prompts
### `triage_ip`
Generate security analyst triage notes for an IP address.
**Parameters:**
- `ip_data` (required): IP check data from AbuseIPDB
## Configuration
All configuration is done via environment variables. Copy `.env.example` to `.env` and customize:
### Required Settings
- `ABUSEIPDB_API_KEY`: Your AbuseIPDB API key
### Optional Settings
- `MAX_AGE_DAYS`: Default report age limit (default: 30)
- `CONFIDENCE_THRESHOLD`: Default confidence threshold (default: 75)
- `DAILY_QUOTA`: API request quota (default: 1000)
- `CACHE_DB_PATH`: SQLite cache file location (default: ./cache.db)
- `LOG_LEVEL`: Logging level (default: INFO)
- `ALLOW_PRIVATE_IPS`: Allow checking private IPs (default: false)
## Usage Examples
### Basic IP Check
```
Check the reputation of 8.8.8.8
```
### Log Analysis
```
Analyze this log line for threats:
192.168.1.100 - - [10/Jan/2024:10:00:00 +0000] "GET /admin/login.php HTTP/1.1" 200 1234
```
### Bulk Analysis
```
Check these IPs for malicious activity:
- 203.0.113.100
- 198.51.100.50
- 192.0.2.25
```
### Security Investigation
```
I'm investigating suspicious activity from 203.0.113.100. Can you:
1. Check its reputation with detailed reports
2. Analyze the surrounding network block
3. Generate triage notes for our security team
```
See `examples/queries.md` for more detailed examples.
## Docker Deployment
Build and run with Docker:
```bash
# Build the image
docker build -f docker/Dockerfile -t mcp-abuseipdb .
# Run the container
docker run -e ABUSEIPDB_API_KEY=your_key_here mcp-abuseipdb
```
## Development
### Setup Development Environment
```bash
pip install -e ".[dev]"
pre-commit install
```
### Run Tests
```bash
pytest
```
## Security Considerations
- **API Key Protection**: Never commit API keys to version control
- **Private IP Filtering**: Private IPs are blocked by default
- **Rate Limiting**: Built-in quota management prevents API abuse
- **Input Validation**: All inputs are validated and sanitized
- **Caching**: Reduces API calls and improves performance
## Rate Limits
AbuseIPDB free tier provides 1,000 requests per day. This server:
- Implements intelligent caching to minimize API usage
- Provides rate limiting with configurable quotas
- Gracefully handles rate limit errors with backoff
## Troubleshooting
### "Unauthorized API key" Error in Claude App
If you're getting unauthorized API key errors when using the MCP server with Claude:
1. **Verify API Key Configuration**:
```bash
# Test your API key with the diagnostic script
python diagnostics/api_auth_diagnostic.py
```
2. **Check Claude App Configuration**:
- Ensure your `mcp.json` has the correct API key in the `env` section
- Verify the `cwd` path points to your project directory
- Make sure the API key value matches exactly (no extra spaces)
3. **Use Enhanced Startup Script**:
- Switch to Option 1 configuration (enhanced startup script)
- Check the server logs in Claude app for diagnostic messages
- Look for `[MCP AbuseIPDB]` prefixed messages
4. **Environment Variable Issues**:
- Ensure your `.env` file is in the project root directory
- Verify the API key in `.env` matches your Claude app configuration
- Check that the API key is valid on the AbuseIPDB website
5. **Debug Steps**:
```bash
# Test local server startup
python scripts/start_mcp_server.py
# Check environment loading
python -c "from mcp_abuseipdb.settings import Settings; print('API key loaded:', bool(Settings().abuseipdb_api_key))"
```
### Common Issues
- **"No .env file found"**: Make sure `.env` exists in project root or set API key in Claude app config
- **"Settings API key: EMPTY"**: API key not properly loaded from environment
- **"Environment var: EMPTY"**: API key not set in Claude app MCP configuration
- **Connection timeouts**: Check your internet connection and AbuseIPDB service status
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the test suite and linting
5. Submit a pull request
## License
MIT License — see [LICENSE](LICENSE) for details.
## Support
- Documentation: See `examples/` directory
- Issues: Please report bugs and feature requests via GitHub issues
- API Documentation: [AbuseIPDB API Docs](https://docs.abuseipdb.com/)
## Changelog
### v0.1.0
- Initial release
- Basic IP checking functionality
- CIDR block analysis
- Blacklist access
- Bulk operations
- Log enrichment
- Caching and rate limiting
- Docker support
