WHOIS MCP

A WHOIS lookup service implemented as a Model Context Protocol (MCP) server.

Overview

WHOIS MCP is a Java application that provides WHOIS lookup functionality through the Model Context Protocol. It allows users to query WHOIS information for domains using a standardized interface. The server communicates over standard input/output, making it compatible with MCP clients.

Demo

https://github.com/user-attachments/assets/037a30de-c330-4dd4-93c2-2add936b9caf

https://github.com/user-attachments/assets/2a91045a-b922-4832-9500-dc9eacb54ee0

https://github.com/user-attachments/assets/befbb1e0-137c-4534-b7f7-433305a41755

Features

• Domain validation and sanitization
• Caching of WHOIS server information
• Fallback to IANA WHOIS server when specific servers are not found
• Comprehensive error handling
• Integration with the Model Context Protocol

Installation

Prerequisites

• Java 21 or higher
• Maven 3.6 or higher

Building the Project

1. Clone the repository:

   git clone https://github.com/asjordi/whois-mcp.git
   cd whois-mcp
   

2. Build with Maven:

   mvn clean package
   

This will create an executable JAR file in the target directory.

3. You can open the project in your favorite IDE (e.g., IntelliJ IDEA, Eclipse) for easier development and debugging.

Debugging the Server

To debug the server, you can use the MCP Inspector.

1. First build the project with:

mvn clean package

2. Run the MCP Inspector with the following command:

npx @modelcontextprotocol/inspector

3. Set the following values:

• Transport: STDIO
• Command: java
• Arguments: -jar PATH\\\\target\\\\whois-mcp-1.0-SNAPSHOT.jar

4. Click on the Connect button to start the MCP Inspector and connect to the server.

Usage

Once configured, the WHOIS MCP server will be automatically available to any MCP client that supports the protocol.

Claude

Go to Menu > File > Settings > Developer > Edit Config and add the following to your claude_desktop_config.json file:

{
   "mcpServers": {
      "whois-mcp-server": {
         "command": "java",
         "args": [
            "-jar",
            "PATH\\\\target\\\\whois-mcp-1.0-SNAPSHOT.jar"
         ]
      }
   }
}

Save the file and restart the application. You can now use the WHOIS MCP server by sending requests to it.

VSCode

Open settings.json and add the following configuration:

"mcp": {
 "servers": {
   "whois-mcp-server": {
     "type": "stdio",
     "command": "java",
     "args": [
       "-jar",
       "PATH\\\\whois-mcp\\\\target\\\\whois-mcp-1.0-SNAPSHOT.jar"
     ]
   }
 }
}

Save the file and restart the application. Open Copilot and set mode to Agent to use the WHOIS MCP server.

Project Structure

The project is structured around the following key components:

Main Components

• Main: Entry point of the application that initializes and starts the MCP server.
• WhoisService: Core service that performs WHOIS queries using the Apache Commons Net library.
• WhoisCache: Caches WHOIS server information based on domain extensions.
• DomainValidatorUtil: Validates domain names using the Apache Commons Validator.
• DomainSanitizer: Sanitizes domain names by removing unnecessary characters and ensuring proper formatting.
• McpException: Custom exception class for handling errors specific to the WHOIS MCP server.

Flow

1. The MCP server receives a request with a domain name.
2. The domain is validated and sanitized.
3. The appropriate WHOIS server is determined from the cache based on the domain extension.
4. A WHOIS query is performed against the server.
5. The result is returned to the client through the MCP protocol.

Whois Server Mapping

WHOIS server mappings are configured in the whois-servers.properties file, which maps top-level domains to their respective WHOIS servers. If this file is not available, a default set of servers is used.

Dependencies

• Model Context Protocol SDK: For implementing the MCP server
• SLF4J: For logging
• Apache Commons Net: For WHOIS client functionality
• Apache Commons Validator: For domain validation
• JUnit Jupiter: For testing

Testing

The project includes comprehensive unit tests for all components. Run the tests with:

mvn test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Jordi Ayala - asjordi.dev

Root Zone Database