IR Toolshed MCP Server

# IR Toolshed MCP Server A comprehensive Model Context Protocol (MCP) server providing incident response and network analysis tools for security professionals. This server allows AI agents like Claude to perform various network-related lookups and analyses to assist with security investigations. ## Overview The IR Toolshed MCP Server provides a suite of networking and security tools accessible via the Model Context Protocol. It's designed to be a general-purpose service for network incident responders, enabling them to perform basic lookups using: - ASN (Autonomous System Number) lookups - DNS lookups and analysis - WHOIS record retrieval - IP geolocation - And more network analysis capabilities to come Each tool is accompanied by detailed documentation as a resource, making it easy for AI systems to understand how to use the tools and what output to expect. ## Current Tools ### ASN Lookup Tool The ASN lookup tool returns information about an IP address including: - The IP address that was queried - The AS number associated with the IP address - The name of the organization that owns the AS number ### DNS Lookup Tool The DNS lookup tool provides DNS record information for domains: - Supports multiple record types (A, AAAA, MX, NS, TXT) - Returns formatted DNS records - Handles both IPv4 and IPv6 queries ### WHOIS Lookup Tool The WHOIS lookup tool retrieves domain registration information: - Domain ownership details - Registration dates - Nameserver information - Registrar details ### Geolocation Tool The IP geolocation tool provides location information using MaxMind's GeoLite2 database: - Country and city-level location data - Latitude and longitude coordinates - Network information - Timezone data Note: The geolocation tool requires a MaxMind license key. You can: 1. Get a free key from: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data 2. Either: - Set the MAXMIND_LICENSE_KEY environment variable - Provide it as a parameter when using the tool - Enter it when prompted More tools will be added in future releases. ## Prerequisites - Python 3.8 or newer (3.13+ recommended) - [uv](https://github.com/astral-sh/uv) Python package manager ## Installation 1. Clone this repository: ```bash git clone <repository-url> cd ir-toolshed-mcp-server ``` 2. Create a virtual environment: ```bash uv venv ``` 3. Activate the virtual environment: #### On Windows: ```bash .venv\Scripts\activate ``` #### On macOS/Linux: ```bash source .venv/bin/activate ``` 4. Install the package in development mode: ```bash uv pip install -e . ``` ## Running the Server Start the MCP server with: ```bash uv run mcp dev src/mcp_server.py ``` This will launch the server in development mode, making it available to MCP clients like Claude Desktop. ## Using the Tools ### ASN Lookup Tool When connected to an MCP client such as Claude Desktop, you can use the ASN lookup tool by providing an IP address: ``` asnlookup("8.8.8.8") ``` Example output: ```json { "ip_addr": "8.8.8.8", "as_number": "15169", "as_name": "GOOGLE - Google LLC" } ``` ### DNS Lookup Tool When connected to an MCP client such as Claude Desktop, you can use the DNS lookup tool by providing a domain: ``` dnslookup("example.com") ``` Example output: ```json { "domain": "example.com", "record_type": "A", "record_value": "93.184.216.34" } ``` ### WHOIS Lookup Tool When connected to an MCP client such as Claude Desktop, you can use the WHOIS lookup tool by providing a domain: ``` whoislookup("example.com") ``` Example output: ```json { "domain": "example.com", "ownership_details": "Google LLC", "registration_date": "2004-04-26", "nameserver_information": "ns1.google.com", "registrar_details": "MarkMonitor Inc." } ``` ### Geolocation Tool When connected to an MCP client such as Claude Desktop, you can use the geolocation tool by providing an IP address: ``` geolocation("8.8.8.8") ``` Example output: ```json { "ip_addr": "8.8.8.8", "country": "US", "city": "Mountain View", "latitude": 37.40599, "longitude": -122.078514, "network": "AS15169 Google LLC", "timezone": "America/Los_Angeles" } ``` ## Error Handling Each tool follows a consistent error handling pattern: General error response format: ```json { "status": "error", "error": "Detailed error message", "query": "Original query value" } ``` Tool-specific error examples: ASN Lookup: ```json { "ip_addr": "<queried-ip>", "status": "error", "error": "Invalid IP address format" } ``` DNS Lookup: ```json { "domain": "<queried-domain>", "record_type": "<requested-type>", "status": "error", "error": "DNS resolution failed" } ``` WHOIS Lookup: ```json { "domain": "<queried-domain>", "status": "error", "error": "WHOIS server not available" } ``` Geolocation: ```json { "ip_addr": "<queried-ip>", "status": "error", "error": "MaxMind database not found or license key invalid" } ``` ## Project Structure The project follows a standard Python package structure: ``` irtoolshed_mcp_server/ # Main package directory ├── __init__.py # Package initialization ├── asnlookup.py # ASN lookup functionality ├── dnslookup.py # DNS lookup functionality ├── geolookup.py # Geolocation functionality ├── mcp_server.py # Main MCP server implementation └── whoislookup.py # WHOIS lookup functionality tests/ # Test directory ├── test_asnlookup.py # ASN lookup tests ├── test_dnslookup.py # DNS lookup tests ├── test_geolookup.py # Geolocation tests └── test_whoislookup.py # WHOIS lookup tests ``` ## Development ### Setting Up Development Environment 1. Clone this repository: ```bash git clone <repository-url> cd ir-toolshed-mcp-server ``` 2. Create a virtual environment and install dependencies: ```bash uv venv source .venv/bin/activate # On Windows use: .venv\Scripts\activate uv pip install -e ".[dev]" ``` ### Running Tests To run the test suite: ```bash uv run pytest ``` This will: - Run all tests in the `tests/` directory - Show test coverage information - Display detailed output for any failures Note: Some tests require additional configuration: - Geolocation tests require a MaxMind GeoLite2 database and license key - WHOIS tests may fail if the WHOIS service is unavailable ### Code Quality The project uses several tools to maintain code quality: - Format code with Black: ```bash uv run black . ``` - Sort imports with isort: ```bash uv run isort . ``` - Run type checking with mypy: ```bash uv run mypy . ``` - Run linting with ruff: ```bash uv run ruff . ``` ## Roadmap Completed: ✓ ASN lookups ✓ DNS record lookups (A, AAAA, MX, etc.) ✓ WHOIS record retrieval ✓ IP geolocation services Future tools planned for inclusion: - Domain reputation scoring - SSL certificate analysis - Network port scanning - Threat intelligence integration - Passive DNS history - Email security analysis (SPF, DKIM, DMARC) - BGP route analysis - Network traffic visualization - Malware hash lookups - URL reputation checking ## Contributing Contributions to add new IR tools or improve existing ones are welcome. Please follow these steps: 1. Fork the repository 2. Create a feature branch 3. Add your tool following the existing pattern in mcp_server.py 4. Include appropriate documentation as a resource 5. Submit a pull request with a clear description of your changes ## License Apache 2.0 ## Security Considerations This server is intended for legitimate security research and incident response. Users must ensure they comply with all applicable laws and regulations when using these tools.