Boilerplate

Clone the boilerplate repository and install Node.js dependencies. This is the starting point for both using the IP lookup tools and customizing the server for your own use case.

git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server
npm install

Compile the TypeScript code to JavaScript. The build output is required before running the server or CLI.

npm run build

Set optional environment variables to customize behavior. IPAPI_API_TOKEN enables extended geolocation features; DEBUG enables verbose logging. These can be set in your shell or in the MCP client config's env block.

# Optional: extend ip-api.com capabilities
export IPAPI_API_TOKEN=your_token_here
export DEBUG=false
export TRANSPORT_MODE=stdio   # or 'http'
export PORT=3000

Before connecting an MCP client, verify the server works by running the built-in CLI commands to look up IP addresses.

npm run cli -- get-ip-details 8.8.8.8
npm run cli -- get-ip-details 8.8.8.8 --include-extended-data
npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"

Add the boilerplate server to your Claude Desktop configuration. Use the absolute path to the built server entry point.

{
  "mcpServers": {
    "boilerplate": {
      "command": "node",
      "args": ["/absolute/path/to/boilerplate-mcp-server/dist/index.js"],
      "env": {
        "TRANSPORT_MODE": "stdio",
        "DEBUG": "false",
        "IPAPI_API_TOKEN": "optional_token"
      }
    }
  }
}

Replace or extend the IP lookup tools with your own domain logic. The `src/tools/` directory contains the tool definitions and `src/resources/` contains the URI template implementations — follow the same patterns to add new tools.

# Run in development with hot-reload inspection:
npm run mcp:inspect