phpipam-mcp-server by arunhotra - MCP Server

phpIPAM MCP Server

Model Context Protocol server for phpIPAM IP address management and network infrastructure.

Installation

Prerequisites

Python 3.10+
phpIPAM instance with API access
App configured in phpIPAM with "SSL with App Code token" security

From PyPI (when published)

pip install phpipam-mcp-server

From Source

git clone https://github.com/InfraMCP/phpipam-mcp-server.git
cd phpipam-mcp-server
pip install -e .

Development Installation

pip install -e ".[dev]"

Usage

Configuration

There are two ways to configure the server:

Option 1: Local Configuration File (Recommended)

Create a config.json file in the project root directory:

# Copy the example config
cp config.json.example config.json

# Edit with your phpIPAM details

The config.json file should contain:

{
  "phpipam_url": "https://ipam.example.com/",
  "phpipam_app_id": "your_app_id",
  "phpipam_app_code": "your_app_code_token"
}

Note: config.json is gitignored and will not be committed to version control.

Option 2: Environment Variables

Alternatively, set environment variables in your MCP client configuration:

{
  "mcpServers": {
    "phpipam": {
      "command": "phpipam-mcp-server",
      "env": {
        "PHPIPAM_URL": "https://ipam.example.com/",
        "PHPIPAM_APP_ID": "your_app_id",
        "PHPIPAM_APP_CODE": "your_app_code_token"
      }
    }
  }
}

Priority: If config.json exists, it will be used. Otherwise, environment variables will be used.

As MCP Server

For config file approach:

{
  "mcpServers": {
    "phpipam": {
      "command": "phpipam-mcp-server"
    }
  }
}

Available Tools

`list_sections(include_fields="")`

List all IP sections from phpIPAM.

include_fields: Comma-separated fields or "all" for complete data

`get_section_subnets(section_id, include_usage=True, include_fields="", limit=20)`

Get subnets within a specific section.

section_id: Section ID to query
include_usage: Include usage statistics (default: True)
include_fields: Field filtering options
limit: Maximum results to return (default: 20, max: 100)

`search_addresses(ip_or_hostname, limit=10)`

Search for IP addresses or hostnames.

ip_or_hostname: IP address or hostname to search for
limit: Maximum results to return (default: 10, max: 50)

`get_subnet_details(subnet_id, include_addresses=False, address_limit=10)`

Get detailed subnet information.

subnet_id: Subnet ID to query
include_addresses: Include IP addresses in subnet (default: False)
address_limit: Maximum addresses to show (default: 10, max: 50)

`list_vlans(domain_id=None, limit=20)`

List VLANs from phpIPAM.

domain_id: Optional domain ID filter
limit: Maximum results to return (default: 20, max: 100)

`list_vrfs(limit=20)`

List VRF instances from phpIPAM.

limit: Maximum results to return (default: 20, max: 100)

`list_locations(limit=20)`

List physical locations for network infrastructure.

limit: Maximum results to return (default: 20, max: 100)

`list_nameservers(limit=20)`

List DNS nameservers with configuration details.

limit: Maximum results to return (default: 20, max: 100)

`search_subnets(query, limit=10)`

Search subnets by CIDR, description, or other criteria.

query: Search term (CIDR, description, etc.)
limit: Maximum results to return (default: 10, max: 50)

Write Operations

`create_subnet(section_id, subnet, mask, *, description="", vlan_id=None)`

Create a new subnet in phpIPAM.

section_id: Section ID where subnet will be created
subnet: Network address (e.g., "192.168.1.0")
mask: Subnet mask (e.g., "24")
description: Optional description for the subnet
vlan_id: Optional VLAN ID

`reserve_ip_address(subnet_id, ip=None, hostname="", description="", owner="")`

Reserve an IP address in a subnet.

subnet_id: Subnet ID where IP will be reserved
ip: Specific IP address to reserve (optional - will find first available)
hostname: Hostname for the IP address
description: Description for the IP address
owner: Owner of the IP address

`update_ip_address(address_id, hostname=None, description=None, owner=None)`

Update an existing IP address record.

address_id: ID of the IP address to update
hostname: New hostname (optional)
description: New description (optional)
owner: New owner (optional)

`delete_ip_address(address_id)`

Delete/release an IP address reservation.

address_id: ID of the IP address to delete

`update_subnet(subnet_id, description=None, vlan_id=None, vrf_id=None)`

Update an existing subnet.

subnet_id: ID of the subnet to update
description: New description (optional)
vlan_id: New VLAN ID (optional)
vrf_id: New VRF ID (optional)

`delete_subnet(subnet_id)`

Delete a subnet (WARNING: This will delete all IP addresses in the subnet).

subnet_id: ID of the subnet to delete

Configuration

phpIPAM Setup

Create an API application in phpIPAM admin interface
Set security to "SSL with App Code token"
Note the App ID and App Code
Set appropriate permissions for the application

Authentication

This server uses static app code token authentication:

No token expiration
Simple configuration
Secure over HTTPS

Development

Code Quality

# Run pylint
python -m pylint src/phpipam_mcp_server/

# Run tests (when available)
python -m pytest

# Format code
python -m black src/
python -m isort src/

Project Structure

src/phpipam_mcp_server/
├── __init__.py          # Package initialization
└── server.py            # Main MCP server implementation

API Documentation

See the docs/ directory for detailed API documentation:

api-overview.md - General API information
controllers.md - Available endpoints and data structures
examples.md - Request/response examples
mcp-design.md - MCP server design and architecture

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make changes with tests
Run code quality checks
Submit a pull request

Support

GitHub Issues: https://github.com/InfraMCP/phpipam-mcp-server/issues
Documentation: https://github.com/InfraMCP/phpipam-mcp-server#readme