phpIPAM MCP Server

Complete Model Context Protocol server for phpIPAM - Professional IP address management and network infrastructure automation through AI assistants.

Manage your entire IP infrastructure through natural language conversations with Claude or other MCP-compatible AI assistants.

🌟 Features

• 63 Comprehensive Tools - Complete phpIPAM API coverage
• 10 Core Modules - Sections, Subnets, Addresses, VLANs, VRFs, Devices, Locations, and more
• Natural Language Interface - Interact with your network through AI assistants
• Production Ready - Docker deployment, health checks, comprehensive logging
• Advanced Search - Find resources by IP, hostname, MAC address, or tags
• Real-time Usage Stats - Monitor subnet utilization and capacity
• Network Planning - Plan allocations, find free IPs, manage hierarchies

📑 Table of Contents

• Quick Start
• Installation
• Usage Examples
• Available Tools
• Configuration
• Deployment
• Development

🚀 Quick Start

Docker Deployment (Recommended)

# Clone repository
git clone https://github.com/0xEkho/phpIPAM-MCP.git
cd phpIPAM-MCP/deploy

# Configure credentials
cp .env.example .env
nano .env  # Add your phpIPAM URL and credentials

# Start server
docker-compose up -d

# Verify health
curl http://localhost:8081/healthz

Python Installation

# Install
pip install -e .

# Set environment variables
export PHPIPAM_URL="https://ipam.example.com"
export PHPIPAM_APP_ID="mcp-server"
export PHPIPAM_APP_CODE="your_app_code_token"

# Run server
phpipam-mcp-server

📥 Installation

Prerequisites

• Python 3.11+ or Docker
• phpIPAM instance with API access
• API application configured with "SSL with App Code token" security

phpIPAM API Setup

1. Login to phpIPAM as administrator
2. Navigate to Administration → phpIPAM settings → API
3. Click Create API application
4. Configure:
   • App ID: mcp-server (or your choice)
   • App permissions: Read/Write as needed
   • App security: SSL with App code token
5. Save and copy the App Code token

From Source

git clone https://github.com/0xEkho/phpIPAM-MCP.git
cd phpIPAM-MCP
pip install -r requirements.txt
pip install -e .

💡 Usage Examples

Browse practical examples in the examples/ directory:

• List Sections - Explore network organization
• Subnet Management - Manage subnets and usage
• IP Address Search - Find IPs by various criteria
• VLAN Management - Audit and manage VLANs
• IP Reservation - Reserve and allocate IPs

Example: Search for an IP

Natural language (with Claude):

"Find all information about IP address 192.168.1.100"

MCP Tool Call:

{
  "tool": "phpipam.addresses.search",
  "args": {
    "search_term": "192.168.1.100"
  }
}

Example: Reserve an IP

Natural language (with Claude):

"Reserve IP 10.0.1.50 with hostname web-server-01 for the production web server"

MCP Tool Call:

{
  "tool": "phpipam.addresses.create",
  "args": {
    "subnet_id": "42",
    "ip": "10.0.1.50",
    "hostname": "web-server-01",
    "description": "Production web server",
    "owner": "IT Team"
  }
}

🛠️ Available Tools

63 Comprehensive Tools

Module	Tools	Description
Sections	6	Organize IP address space into sections
Subnets	11	Complete subnet lifecycle management
Addresses	11	IP address allocation and tracking
VLANs	10	VLAN and L2 domain management
VRFs	7	Virtual routing and forwarding
Devices	8	Network device inventory
Locations	6	Physical location tracking
Nameservers	2	DNS nameserver management
Tools	2	Global search and utilities

Key Operations

Sections

• phpipam.sections.list - List all sections
• phpipam.sections.get - Get section details
• phpipam.sections.get_subnets - List subnets in section
• phpipam.sections.create/update/delete - Manage sections

Subnets

• phpipam.subnets.list - List all subnets
• phpipam.subnets.get - Get subnet with usage stats
• phpipam.subnets.search - Search by CIDR
• phpipam.subnets.get_first_free - Find next available IP
• phpipam.subnets.get_slaves - List child subnets
• phpipam.subnets.create/update/delete - Manage subnets

Addresses

• phpipam.addresses.search - Search by IP or hostname
• phpipam.addresses.search_mac - Search by MAC address
• phpipam.addresses.create - Reserve IP addresses
• phpipam.addresses.update/delete - Manage addresses
• phpipam.addresses.ping - Ping an IP address
• phpipam.addresses.tags.* - Manage address tags

VLANs

• phpipam.vlans.list - List all VLANs
• phpipam.vlans.get_subnets - Subnets in VLAN
• phpipam.vlans.domains.* - Manage L2 domains
• phpipam.vlans.create/update/delete - Manage VLANs

VRFs, Devices, Locations

• Complete CRUD operations for each resource type
• Search and filtering capabilities
• Relationship tracking (devices ↔ addresses, locations ↔ subnets)

See examples/ for detailed usage of each tool.

⚙️ Configuration

Environment Variables

# Required
PHPIPAM_URL=https://ipam.example.com
PHPIPAM_APP_ID=mcp-server
PHPIPAM_APP_CODE=your_app_code_token

# Optional
PHPIPAM_VERIFY_SSL=true
PHPIPAM_TIMEOUT=30
LOG_LEVEL=INFO

Configuration File

Alternatively, use config.yaml:

phpipam:
  url: "https://ipam.example.com"
  app_id: "mcp-server"
  app_code: "your_app_code_token"
  verify_ssl: true
  timeout: 30

server:
  host: "0.0.0.0"
  port: 8081
  log_level: "INFO"

MCP Client Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "phpipam": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PHPIPAM_URL=https://ipam.example.com",
        "-e", "PHPIPAM_APP_ID=mcp-server",
        "-e", "PHPIPAM_APP_CODE=your_token",
        "phpipam-mcp-server"
      ]
    }
  }
}

Or with Python:

{
  "mcpServers": {
    "phpipam": {
      "command": "python",
      "args": ["-m", "phpipam_server.main"],
      "env": {
        "PHPIPAM_URL": "https://ipam.example.com",
        "PHPIPAM_APP_ID": "mcp-server",
        "PHPIPAM_APP_CODE": "your_token"
      }
    }
  }
}

🐳 Deployment

Complete deployment guide available in deploy/README.md.

Docker Compose

cd deploy
docker-compose up -d

Docker Build

docker build -t phpipam-mcp-server -f deploy/Dockerfile .
docker run -d -p 8081:8081 \
  -e PHPIPAM_URL="..." \
  -e PHPIPAM_APP_ID="..." \
  -e PHPIPAM_APP_CODE="..." \
  phpipam-mcp-server

Health Check

curl http://localhost:8081/healthz

🔧 Development

Setup Development Environment

# Clone and install
git clone https://github.com/0xEkho/phpIPAM-MCP.git
cd phpIPAM-MCP
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e ".[dev]"

Run Tests

pytest tests/
pytest --cov=phpipam_server tests/

Code Quality

# Format
black phpipam_server/
isort phpipam_server/

# Lint
ruff check phpipam_server/
mypy phpipam_server/

Project Structure

phpIPAM-MCP/
├── phpipam_server/          # Main application code
│   ├── main.py             # FastAPI server
│   ├── api_client.py       # phpIPAM API client
│   ├── config.py           # Configuration management
│   ├── tools.py            # MCP tools implementation
│   ├── tool_definitions.py # Tool metadata
│   └── modules/            # API modules (10 modules)
├── deploy/                  # Docker deployment
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── README.md
├── examples/                # Usage examples (.md files)
├── tests/                   # Test suite
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Package configuration
└── README.md               # This file

🔒 Security

• Authentication: App code token-based (static, no expiration)
• Transport: HTTPS required for production
• Permissions: Configure appropriate API permissions in phpIPAM
• Environment: Store credentials securely, never commit secrets
• Docker: Runs as non-root user
• SSL Verification: Enabled by default

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for Model Context Protocol by Anthropic
• Inspired by ALE OmniSwitch MCP
• Based on phpIPAM API

📞 Support

• Issues: GitHub Issues
• Examples: Usage Examples
• Deployment: Deploy Guide
• phpIPAM API: Official Documentation

---

Made with ❤️ for network automation and AI-assisted IPAM operations