phpIPAM MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@phpIPAM MCP Server list all subnets in section Office"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 (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-mcpFrom 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.jsConfiguration
All configuration is done through environment variables:
Required Settings
Variable | Description | Example |
| Base URL of phpIPAM instance |
|
| API application ID |
|
| phpIPAM username |
|
| phpIPAM password |
|
phpIPAM API Setup
Log in to phpIPAM as an administrator
Go to Administration > API
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)
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 |
|
| Enable write operations (allocate, release, upsert) |
|
| Verify TLS certificates |
|
| Cache API responses (60s TTL) |
|
| Log HTTP request/response details |
|
| Allow subnet creation via |
|
| Allow section creation via |
Performance Settings
Variable | Default | Description |
|
| Request timeout in milliseconds |
|
| Maximum retry attempts |
|
| Base retry delay in milliseconds |
Available Tools
Read Operations (Always Available)
Tool | Description |
| Check connectivity and authentication |
| List all sections |
| Get section by ID or name |
| List subnets in a section |
| Get subnet by ID or CIDR |
| List addresses in a subnet |
| Get address by ID or IP |
| Search by IP, hostname, or MAC |
Write Operations (Require PHPIPAM_WRITE_ENABLED=true)
Tool | Description |
| Allocate first free IP in subnet |
| Release (delete) an IP address |
| Create or update an IP address |
Create Operations (Require Additional Toggles)
Tool | Required Toggle | Description |
|
| Create subnet if not exists |
|
| 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
Search for existing assignment:
phpipam.search { "query": "webserver01" }Find available subnet:
phpipam.subnets.list { "sectionId": "1" }Allocate IP:
phpipam.addresses.allocate { "subnetId": "5", "hostname": "webserver01" }
Audit IP Usage
List sections:
phpipam.sections.listList subnets:
phpipam.subnets.list { "sectionId": "1" }View addresses:
phpipam.addresses.list { "subnetId": "5" }
Release IP
Find the IP:
phpipam.addresses.get { "ip": "192.168.1.50" }Release it:
phpipam.addresses.release { "ip": "192.168.1.50" }
Error Handling
The server returns structured errors with these codes:
Code | Description | Retryable |
| Authentication failure | No |
| Invalid input parameters | No |
| Resource not found | No |
| Resource conflict (duplicate) | No |
| Operation not permitted (toggle disabled) | No |
| Transient error (timeout, 5xx) | Yes |
| Unexpected server error | No |
Security Considerations
Read-Only by Default: Write operations require explicit opt-in
Granular Permissions: Subnet/section creation have separate toggles
TLS Verification: Enabled by default, only disable for development
No Secret Logging: Credentials are never logged (even with debug enabled)
Non-Root Container: Docker image runs as unprivileged user
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 buildLicense
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
Available Tools
13 toolsphpipam.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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Connect LLM tools to your Algolia account with user-scoped access for internal workflows.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.3Apache 2.0
- AlicenseDqualityCmaintenanceEnables managing MikroTik RouterOS devices via natural language, with read-heavy network inspection and guarded write access across multiple routers.261Apache 2.0
- AlicenseBqualityCmaintenanceGives AI assistants read (and optionally write) access to a NetBox instance, covering DCIM, IPAM, circuits, virtualization, tenancy, and more.10047 npm1MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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.-