Skip to main content
Glama
phpIPAM MCP Server

phpIPAM MCP Server

by alsamasu

phpIPAM MCP Server

A Model Context Protocol (MCP) server for phpIPAM IP Address Management. This server enables LLMs to manage IP addresses, subnets, and network sections through natural language.

Features

  • Full IPAM Operations: List, search, allocate, and release IP addresses

  • Subnet Management: View and create subnets with proper CIDR validation

  • Section Organization: Manage phpIPAM sections for logical grouping

  • Security First: Write operations disabled by default with granular toggles

  • Retry Logic: Automatic retry with exponential backoff for transient errors

  • Docker Ready: Minimal container image with non-root user

Related MCP server: MikroTik RouterOS MCP

Quick Start

docker run -i --rm \
  -e PHPIPAM_BASE_URL=https://phpipam.example.com \
  -e PHPIPAM_APP_ID=myapp \
  -e PHPIPAM_USERNAME=admin \
  -e PHPIPAM_PASSWORD=your-password \
  mcp/phpipam-mcp

From Source

# Clone the repository
git clone https://github.com/alsamasu/phpipam-mcp.git
cd phpipam-mcp

# Install dependencies
npm install

# Build
npm run build

# Run (with environment variables set)
node dist/index.js

Configuration

All configuration is done through environment variables:

Required Settings

Variable

Description

Example

PHPIPAM_BASE_URL

Base URL of phpIPAM instance

https://phpipam.example.com

PHPIPAM_APP_ID

API application ID

myapp

PHPIPAM_USERNAME

phpIPAM username

admin

PHPIPAM_PASSWORD

phpIPAM password

your-password

phpIPAM API Setup

  1. Log in to phpIPAM as an administrator

  2. Go to Administration > API

  3. Create a new API application:

    • App ID: Choose a name (e.g., myapp)

    • App Security: Select User token

    • App permissions: Set based on your needs (read/write/admin)

  4. Use the App ID and your phpIPAM credentials with this server

Feature Toggles

All write operations are disabled by default for security:

Variable

Default

Description

PHPIPAM_WRITE_ENABLED

false

Enable write operations (allocate, release, upsert)

PHPIPAM_VERIFY_TLS

true

Verify TLS certificates

PHPIPAM_ENABLE_CACHE

false

Cache API responses (60s TTL)

PHPIPAM_DEBUG_HTTP

false

Log HTTP request/response details

PHPIPAM_ALLOW_SUBNET_CREATE

false

Allow subnet creation via subnets.ensure

PHPIPAM_ALLOW_SECTION_CREATE

false

Allow section creation via sections.ensure

Performance Settings

Variable

Default

Description

PHPIPAM_TIMEOUT

30000

Request timeout in milliseconds

PHPIPAM_MAX_RETRIES

3

Maximum retry attempts

PHPIPAM_RETRY_DELAY

1000

Base retry delay in milliseconds

Available Tools

Read Operations (Always Available)

Tool

Description

phpipam.health

Check connectivity and authentication

phpipam.sections.list

List all sections

phpipam.sections.get

Get section by ID or name

phpipam.subnets.list

List subnets in a section

phpipam.subnets.get

Get subnet by ID or CIDR

phpipam.addresses.list

List addresses in a subnet

phpipam.addresses.get

Get address by ID or IP

phpipam.search

Search by IP, hostname, or MAC

Write Operations (Require PHPIPAM_WRITE_ENABLED=true)

Tool

Description

phpipam.addresses.allocate

Allocate first free IP in subnet

phpipam.addresses.release

Release (delete) an IP address

phpipam.addresses.upsert

Create or update an IP address

Create Operations (Require Additional Toggles)

Tool

Required Toggle

Description

phpipam.subnets.ensure

PHPIPAM_ALLOW_SUBNET_CREATE=true

Create subnet if not exists

phpipam.sections.ensure

PHPIPAM_ALLOW_SECTION_CREATE=true

Create section if not exists

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "phpipam": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PHPIPAM_BASE_URL=https://phpipam.example.com",
        "-e", "PHPIPAM_APP_ID=myapp",
        "-e", "PHPIPAM_USERNAME=admin",
        "-e", "PHPIPAM_PASSWORD=your-password",
        "mcp/phpipam-mcp"
      ]
    }
  }
}

With Write Operations Enabled

{
  "mcpServers": {
    "phpipam": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PHPIPAM_BASE_URL=https://phpipam.example.com",
        "-e", "PHPIPAM_APP_ID=myapp",
        "-e", "PHPIPAM_USERNAME=admin",
        "-e", "PHPIPAM_PASSWORD=your-password",
        "-e", "PHPIPAM_WRITE_ENABLED=true",
        "mcp/phpipam-mcp"
      ]
    }
  }
}

Common Workflows

Lookup and Allocate IP

  1. Search for existing assignment: phpipam.search { "query": "webserver01" }

  2. Find available subnet: phpipam.subnets.list { "sectionId": "1" }

  3. Allocate IP: phpipam.addresses.allocate { "subnetId": "5", "hostname": "webserver01" }

Audit IP Usage

  1. List sections: phpipam.sections.list

  2. List subnets: phpipam.subnets.list { "sectionId": "1" }

  3. View addresses: phpipam.addresses.list { "subnetId": "5" }

Release IP

  1. Find the IP: phpipam.addresses.get { "ip": "192.168.1.50" }

  2. Release it: phpipam.addresses.release { "ip": "192.168.1.50" }

Error Handling

The server returns structured errors with these codes:

Code

Description

Retryable

AUTH

Authentication failure

No

VALIDATION

Invalid input parameters

No

NOT_FOUND

Resource not found

No

CONFLICT

Resource conflict (duplicate)

No

FORBIDDEN

Operation not permitted (toggle disabled)

No

RETRYABLE

Transient error (timeout, 5xx)

Yes

INTERNAL

Unexpected server error

No

Security Considerations

  1. Read-Only by Default: Write operations require explicit opt-in

  2. Granular Permissions: Subnet/section creation have separate toggles

  3. TLS Verification: Enabled by default, only disable for development

  4. No Secret Logging: Credentials are never logged (even with debug enabled)

  5. Non-Root Container: Docker image runs as unprivileged user

  6. Bounded Retries: Maximum 3 retries with exponential backoff

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run linter
npm run lint

# Run tests
npm test

# Build for production
npm run build

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Available Tools

13 tools
phpipam.addresses.allocateA

Allocate the first available IP address in a subnet. Requires PHPIPAM_WRITE_ENABLED=true

Inputs: subnetId (required), mac, note, owner, +2 more.

phpipam.addresses.getA

Get a specific address by ID or IP

Inputs: id, ip.

phpipam.addresses.listA

List all addresses in a subnet

Inputs: subnetId (required).

phpipam.addresses.releaseB

Release (delete) an IP address. Requires PHPIPAM_WRITE_ENABLED=true

Inputs: id, ip.

phpipam.addresses.upsertB

Create or update an IP address. Requires PHPIPAM_WRITE_ENABLED=true

Inputs: ip (required), subnetId (required), mac, note, +3 more.

phpipam.healthA

Check phpIPAM connectivity and authentication status

Inputs: no named parameters.

phpipam.searchA

Search for addresses by IP, hostname, or other criteria

Inputs: query (required), type.

phpipam.sections.ensureA

Ensure a section exists (create if missing). Requires PHPIPAM_WRITE_ENABLED=true and PHPIPAM_ALLOW_SECTION_CREATE=true

Inputs: name (required), description, masterSection.

phpipam.sections.getB

Get a specific section by ID or name

Inputs: id, name.

phpipam.sections.listA

List all sections in phpIPAM

Inputs: no named parameters.

phpipam.subnets.ensureC

Ensure a subnet exists (create if missing). Requires PHPIPAM_WRITE_ENABLED=true and PHPIPAM_ALLOW_SUBNET_CREATE=true

Inputs: cidr (required), sectionId (required), vlanId, description, +1 more.

phpipam.subnets.getA

Get a specific subnet by ID or CIDR notation

Inputs: id, cidr.

phpipam.subnets.listA

List all subnets in a section

Inputs: sectionId (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 13 tools

    Disambiguation4/5

    Tools are mostly distinct, with clear resource-action patterns for sections, subnets, and addresses. Minor ambiguity exists between 'search' and 'addresses.get', but descriptions clarify their different use cases.

    Naming Consistency4/5

    Most tools follow a consistent 'phpipam.<resource>.<action>' pattern. Exceptions include 'phpipam.health' and 'phpipam.search', which omit the resource segment, but the overall style is uniform.

    Tool Count5/5

    13 tools is well-scoped for an IPAM server, covering health checks, sections, subnets, and addresses without excessive redundancy. Each tool serves a clear purpose within the domain.

    Completeness3/5

    Address lifecycle is well covered with allocate, release, and upsert, but sections and subnets lack update and delete operations. The ensure tools provide creation, but no way to modify or remove these entities, leaving notable gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables read-only interaction with NetBox network documentation and infrastructure data through LLMs. Allows querying devices, sites, IP addresses, and viewing change history via natural language.
      3
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to safely troubleshoot networks through read-only tools for device inventory, interface status, VLAN paths, BGP neighbors, route lookups, and interface error detection. Integrates with Microsoft Copilot Studio and Teams for natural-language-driven network diagnostics.
      -