phpIPAM MCP Server

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

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

| 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)

1. 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.

Related Projects

• phpIPAM - Open source IP address management
• Model Context Protocol - Protocol for LLM tool integration
• Docker MCP Catalog - Docker's MCP server registry