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 Python package manager

Installation

1. Clone this repository:

git clone 
cd ir-toolshed-mcp-server

2. Create a virtual environment:

uv venv

3. Activate the virtual environment:

On Windows:

.venv\Scripts\activate

On macOS/Linux:

source .venv/bin/activate

4. Install the package in development mode:

uv pip install -e .

Running the Server

Start the MCP server with:

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:

{
    "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:

{
    "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:

{
    "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:

{
    "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:

{
    "status": "error",
    "error": "Detailed error message",
    "query": "Original query value"
}

Tool-specific error examples:

ASN Lookup:

{
    "ip_addr": "",
    "status": "error",
    "error": "Invalid IP address format"
}

DNS Lookup:

{
    "domain": "",
    "record_type": "",
    "status": "error",
    "error": "DNS resolution failed"
}

WHOIS Lookup:

{
    "domain": "",
    "status": "error",
    "error": "WHOIS server not available"
}

Geolocation:

{
    "ip_addr": "",
    "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:

git clone 
cd ir-toolshed-mcp-server

2. Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
uv pip install -e ".[dev]"

Running Tests

To run the test suite:

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:

uv run black .

• Sort imports with isort:

uv run isort .

• Run type checking with mypy:

uv run mypy .

• Run linting with ruff:

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.

Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!