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: NetBox MCP Server

Quick Start

Docker (Recommended)

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

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:

Performance Settings

Available Tools

Read Operations (Always Available)

Write Operations (Require PHPIPAM_WRITE_ENABLED=true)

Create Operations (Require Additional Toggles)

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:

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.

Related Projects

• phpIPAM - Open source IP address management

• Model Context Protocol - Protocol for LLM tool integration

• Docker MCP Catalog - Docker's MCP server registry