Skip to main content
Glama

nwtools-mcp

An MCP server that gives LLMs accurate IPv4 subnet and address tools. LLMs are unreliable at network math — this server provides deterministic, correct results via Python's ipaddress standard library.

PyPI: https://pypi.org/project/nwtools-mcp/

Tools

Tool

Description

parse_cidr

Network address, broadcast, netmask, wildcard mask, host count

ip_in_subnet

Check whether an IP falls within a subnet

subnets_overlap

Detect overlap between two subnets and return the intersection

cidr_to_range

Convert a CIDR to its first and last IP address

range_to_cidrs

Convert an IP range to the minimal list of covering CIDRs

subtract_subnet

Carve a subnet out of a larger block, returning remaining CIDRs

find_gaps

Find unallocated space within a container block

check_coverage

Check whether a set of CIDRs fully covers a target block

summarize_cidrs

Collapse a list of CIDRs into the minimal set of supernets

classify_ip

Classify an IP as RFC 1918, loopback, link-local, multicast, or public

ip_convert

Convert an IP between dotted-decimal, hex, binary, and integer

Related MCP server: subnet-calculator-mcp

Environment variables

Variable

Default

Description

MCP_TRANSPORT

stdio

stdio, streamable-http, or sse

HOST

0.0.0.0

Bind address (HTTP transports only)

PORT

8000

Listen port (HTTP transports only)

API_KEY

(none)

When set, requires X-API-Key: <value> on all HTTP requests

LOG_LEVEL

INFO

Python log level for process and request logging

Local use (stdio)

The stdio transport is used when Claude Desktop spawns the server as a subprocess. No network port is opened.

Run from PyPI with uvx

The simplest way to run the server locally is:

uvx nwtools-mcp

That runs the nwtools-mcp console command from an isolated ephemeral environment. For a persistent install:

uv tool install nwtools-mcp
nwtools-mcp

Install and run directly:

pip install -e .
python main.py

Or use the console script:

nwtools-mcp

Or install from PyPI with pip:

pip install nwtools-mcp
nwtools-mcp

Or via Docker:

docker run --rm -i nwtools-mcp

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nwtools": {
      "command": "python",
      "args": ["/path/to/nwtools-mcp/main.py"]
    }
  }
}

Or run it directly from PyPI with uvx:

{
  "mcpServers": {
    "nwtools": {
      "command": "uvx",
      "args": ["nwtools-mcp"]
    }
  }
}

If you prefer a persistent uv-managed install, use:

{
  "mcpServers": {
    "nwtools": {
      "command": "nwtools-mcp"
    }
  }
}

Remote deployment (HTTP)

The server supports streamable-http (recommended) and sse transports for remote access. Set MCP_TRANSPORT to switch modes.

Running the HTTP server

# Local test
MCP_TRANSPORT=streamable-http python main.py

# With auth
API_KEY=your-secret MCP_TRANSPORT=streamable-http python main.py

With Docker:

docker build -t nwtools-mcp .
docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e API_KEY=your-secret \
  nwtools-mcp

Operational endpoints

When running in HTTP mode, the container exposes two unauthenticated probe endpoints:

Endpoint

Description

/healthz

Basic liveness probe

/readyz

Readiness probe

HTTP requests are also logged as structured JSON lines, including method, path, status, duration, client IP, and request ID.

TLS and auth

The server does not terminate TLS. In production, place it behind a reverse proxy. Example Caddy config:

nwtools.example.com {
    reverse_proxy localhost:8000
}

The built-in API_KEY check adds a layer of defense at the application level, but it does not replace TLS — never expose the server without it.

Connecting Claude to a remote server

In Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nwtools": {
      "url": "https://nwtools.example.com/mcp",
      "headers": {
        "X-API-Key": "your-secret"
      }
    }
  }
}

On claude.ai, add the server under Settings → Integrations using the same URL.

Development

Install with the test extra and run the suite:

pip install -e ".[test]"
pytest

To build distribution artifacts locally:

uv build

Or with the standard Python build frontend:

pip install build
python -m build

Release

The project is now structured to publish cleanly to PyPI and run via uvx.

Build locally:

uv build

Publish manually:

uv publish

Automated publishing uses publish.yml with PyPI Trusted Publishing.

Release checklist:

  1. Update version in pyproject.toml and __version__ in src/nwtools_mcp/init.py.

  2. Run pytest.

  3. Run uv build.

  4. Commit and push to main.

  5. Push a version tag such as v0.2.0.

Trusted Publisher settings:

  • Create a pypi environment in the GitHub repository settings.

  • Add a Trusted Publisher for this project on PyPI that matches: Repository owner: crims0n Repository name: nwtools-mcp Workflow filename: publish.yml Environment name: pypi

The publish workflow builds the wheel and sdist, smoke-tests both artifacts, and then runs uv publish.

Requirements

  • Python 3.11+

  • mcp

  • uvicorn

Available Tools

11 tools
check_coverageC

Check whether a set of CIDRs fully covers a target block.

Inputs: target_cidr (required), covering_cidrs (required).

cidr_to_rangeC

Convert a CIDR block to its first and last IP address.

Inputs: cidr (required).

classify_ipC

Classify an IPv4 address by its scope and allocation type.

Inputs: ip (required).

find_gapsC

Find unallocated address space within a container block.

Inputs: container_cidr (required), used_cidrs (required).

ip_convertA

Convert an IPv4 address between dotted-decimal, hex, binary, and integer forms.

Inputs: ip (required).

ip_in_subnetC

Check whether an IPv4 address falls within a subnet.

Inputs: ip (required), cidr (required).

parse_cidrC

Parse a CIDR block and return key network properties.

Inputs: cidr (required).

range_to_cidrsA

Convert an inclusive IP address range to the minimal list of covering CIDRs.

Inputs: first_ip (required), last_ip (required).

subnets_overlapB

Check whether two IPv4 subnets overlap.

Inputs: cidr_a (required), cidr_b (required).

subtract_subnetC

Subtract one subnet from another and return the remaining address space as CIDRs.

Inputs: base_cidr (required), remove_cidr (required).

summarize_cidrsA

Collapse a list of CIDRs into the minimal set of covering supernets.

Inputs: cidrs (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, from parsing CIDRs (parse_cidr) to checking coverage (check_coverage) and finding gaps (find_gaps). There is no ambiguity or overlap between tool functionalities.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., classify_ip, summarize_cidrs, subtract_subnet), making the set predictable and easy to navigate.

    Tool Count5/5

    With 11 tools, the server is well-scoped for IP address manipulation tasks. Each tool earns its place, covering essential operations without unnecessary bloat or missing coverage.

    Completeness5/5

    The tool set covers the full lifecycle of common IP networking tasks: parsing, conversion, classification, membership checking, coverage analysis, gap detection, overlap checking, subtraction, summarization, and range conversion. No obvious gaps for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers