Kamailio MCP Server

An AI-powered and shell-callable control plane and developer platform for Kamailio. Connect any MCP-compatible AI client (Claude Desktop, Cursor, Cline, Continue) for natural-language operations — or use the same primitives via the kamailio-mcp CLI for shell scripts, CI pipelines, and external Web Applications / Admin UI Portals.

Features

Related MCP server: Chamade MCP Server

What You Can Do With This MCP Server

kamailio-mcp bridges AI assistants (like Claude, Cursor, and Continue), web applications, and automation pipelines directly with Kamailio SIP servers and their databases.

┌────────────────────────────────────────────────────────────────────────┐
│                        AI Clients & Web UIs                            │
│           (Claude Desktop / Cursor / Web Admin Portals / CI)           │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │  MCP Protocol / CLI
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          Kamailio MCP Server                           │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────┐  │
│  │ Config & Linter  │  │ Live JSONRPC Ops │  │ DB & Provisioning    │  │
│  └────────┬─────────┘  └────────┬─────────┘  └──────────┬───────────┘  │
└───────────┼─────────────────────┼───────────────────────┼──────────────┘
            │                     │                       │
            ▼                     ▼                       ▼
   kamailio.cfg / AST      Kamailio JSONRPC       PostgreSQL / MySQL
   (Templates & Lint)     (Port 8080/8081)         (Port 5432/3306)

1. 🧠 AI-Assisted SIP Engineering & Natural Language Ops

• Ask AI in Plain English: Query your live server with prompts like "Show all active SIP registrations", "Is Kamailio healthy and what is its uptime?", or "Reload the dispatcher gateway table".

• Config Troubleshooting & Generation: Have AI design complete routing blocks, fix NAT traversal logic, or add security filters (pike, htable, secfilter).

• Interactive Documentation Assistant: Search module docs, query parameter types, and compare changes across Kamailio versions (e.g. 5.5.x vs 6.0.x) on the fly.

2. ⚙️ Automated Configuration Management & Linting

• Generate Production Topologies: Instantly build pre-tested kamailio.cfg templates for:

  • Class 4 SBC / Wholesale SIP trunking

  • Residential PBX & Registrar with NAT traversal (RTPengine)

  • SIP Load Balancer & Dispatcher

  • WebRTC to SIP Gateway

  • STIR/SHAKEN Authentication & Verification Proxy

• Smart Capacity Tuning: Automatically calculate optimal shared memory (-m), private memory (-M), and worker process children counts based on your target CPS (Calls Per Second) and concurrent dialogs.

• Semantic Linting & AST Parsing: Check configuration syntax, module loading order (e.g., ensuring tm loads before rr), required modparams, and parse configs into JSON ASTs for visual route builders.

3. ⚡ Real-Time Operational Control (JSONRPC)

• Live Diagnostics: Execute JSONRPC methods (core.uptime, ul.dump, htable.dump, dialog.list) without SSH-ing into the server.

• Zero-Downtime Reloads: Dynamically reload routing tables (dispatcher.reload, drouting.reload, htable.reload) while traffic continues flowing.

• Health Checks: Run structured health audits verifying both JSONRPC responsiveness and database connectivity.

4. 🗄️ Telephony & Database Provisioning

• Subscriber Management: Add, list, and search SIP subscribers (subscriber_create, subscriber_list) with automatic HA1/HA1B password hashing.

• Dispatcher Gateway Provisioning: Add new media servers/gateways (FreeSWITCH, Asterisk, SBCs) to dispatcher sets with custom load-balancing algorithms and priority weights.

• User Location (UsrLoc) Lookups: Inspect registered endpoints, contacts, user agents, and NAT IP/port mappings.

5. 🖥️ Build Custom Web Admin Portals & DevOps Pipelines

• Dynamic Form Generation: Use doc_get_module_schema to export machine-readable JSONSchema definitions of Kamailio modules so your frontend (React, Vue, Next.js) can generate config UIs automatically.

• CI/CD Integration: Run kamailio-mcp cfg lint in GitHub Actions or GitLab CI to catch broken configs before production deployments.

• CLI & Scripting Ready: Every MCP tool is also accessible directly via the kamailio-mcp CLI for bash scripts and cron jobs.

Prerequisites & Installing Dependencies

1. System Prerequisites

On Linux (Debian / Ubuntu / Debian-based systems), install Python 3.10+, pip, venv, compiler tools, and PostgreSQL client header dependencies:

# Debian / Ubuntu
sudo apt-get update && sudo apt-get install -y \
    python3 \
    python3-pip \
    python3-venv \
    python3-dev \
    build-essential \
    libpq-dev \
    curl

# Fedora / RHEL / Rocky Linux
sudo dnf install -y \
    python3 \
    python3-pip \
    python3-devel \
    gcc \
    postgresql-devel

2. Installing Python Package & Dependencies

We recommend using a Python virtual environment to isolate dependencies:

# Navigate to the repository
cd /usr/share/kamalio-mcp-server

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Option A: Install with PostgreSQL support (Recommended)
pip install -e ".[postgres]"

# Option B: Install with MySQL support
pip install -e ".[mysql]"

# Option C: Install all development and testing dependencies
pip install -e ".[postgres,mysql,dev]"

Or simply use the Makefile:

make install

3. Configuration

Copy the example .env file and adjust settings:

cp .env.example .env

Key environment variables:

Deployment Instructions

1. Full Stack via Docker Compose (Quick Start)

Launch Kamailio 6.0, PostgreSQL 16 (pre-seeded with Kamailio tables), and kamailio-mcp with a single command:

docker compose -f docker/docker-compose.yml up -d

This brings up:

• kamailio -- Kamailio listening on SIP UDP/TCP port 5060 and JSONRPC on port 8081 (host).

• postgres -- PostgreSQL 16 initialized with Kamailio's official table schemas on port 5432.

• kamailio-mcp -- MCP server running on port 8080 for SSE and HTTP clients.

To check logs:

docker compose -f docker/docker-compose.yml logs -f kamailio-mcp

2. Running Individual Services via Docker Compose

You can launch and manage any of the three services independently depending on your workflow:

A. Run Only PostgreSQL Database

Starts the pre-seeded PostgreSQL 16 instance on port 5432:

docker compose -f docker/docker-compose.yml up -d postgres
# or via Makefile
make docker-up-db

B. Run Only Kamailio SIP Server

Starts Kamailio (and its PostgreSQL dependency) with JSONRPC exposed on host port 8081:

docker compose -f docker/docker-compose.yml up -d kamailio
# or via Makefile
make docker-up-kamailio

C. Run Only the Kamailio MCP Server

Starts only the MCP server container on port 8080:

docker compose -f docker/docker-compose.yml up -d kamailio-mcp
# or via Makefile
make docker-up-mcp

Monitoring & Stopping Individual Services

# View service-specific logs
docker compose -f docker/docker-compose.yml logs -f postgres
docker compose -f docker/docker-compose.yml logs -f kamailio
docker compose -f docker/docker-compose.yml logs -f kamailio-mcp

# Stop a single service without affecting others
docker compose -f docker/docker-compose.yml stop kamailio
docker compose -f docker/docker-compose.yml stop kamailio-mcp

# Stop all services (preserves data volumes)
make docker-stop

3. Running Standalone Docker Containers (docker run)

If you prefer running standalone containers without Docker Compose, use standard docker run commands with a shared bridge network:

# 1. Create a dedicated Docker network
docker network create kamailio-net

# 2. Run PostgreSQL 16 (with pre-seeded schema)
docker run -d \
  --name kamailio-postgres \
  --network kamailio-net \
  -p 5432:5432 \
  -e POSTGRES_USER=kamailio \
  -e POSTGRES_PASSWORD=kamailio \
  -e POSTGRES_DB=kamailio \
  -v $(pwd)/docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql \
  -v kamailio_pgdata:/var/lib/postgresql/data \
  postgres:16-alpine

# 3. Run Kamailio SIP Server
docker run -d \
  --name kamailio-node \
  --network kamailio-net \
  -p 5060:5060/udp \
  -p 5060:5060/tcp \
  -p 8081:8080 \
  -v $(pwd)/docker/kamailio/kamailio.cfg:/etc/kamailio/kamailio.cfg \
  kamailio/kamailio-ci:5.5.2-alpine \
  kamailio -DD -E -f /etc/kamailio/kamailio.cfg

# 4. Build and Run Kamailio MCP Server
docker build -t kamailio-mcp:latest -f docker/Dockerfile .

docker run -d \
  --name kamailio-mcp-server \
  --network kamailio-net \
  -p 8080:8080 \
  -e KAMAILIO_MCP_RPC_URL="http://kamailio-node:8080/jsonrpc" \
  -e KAMAILIO_MCP_DB_URL="postgresql+asyncpg://kamailio:kamailio@kamailio-postgres:5432/kamailio" \
  -e KAMAILIO_MCP_TRANSPORT="streamable-http" \
  -e KAMAILIO_MCP_HOST="0.0.0.0" \
  -e KAMAILIO_MCP_PORT="8080" \
  kamailio-mcp:latest

4. Hybrid & External Deployment Scenarios

Scenario A: Local Python MCP + Containerized Kamailio & PostgreSQL

Ideal for local development, hot reloading, and debugging MCP Python code directly on your host machine while Kamailio and PostgreSQL run inside Docker:

# 1. Start DB and Kamailio containers
make docker-up-kamailio

# 2. Run MCP server locally on host pointing to exposed host ports
export KAMAILIO_MCP_RPC_URL="http://127.0.0.1:8081/jsonrpc"
export KAMAILIO_MCP_DB_URL="postgresql+asyncpg://kamailio:kamailio@127.0.0.1:5432/kamailio"
kamailio-mcp serve --transport sse --host 127.0.0.1 --port 8080

Scenario B: Containerized MCP Server + Existing External Kamailio Server

If you already run a production Kamailio cluster or standalone instance on a remote server/VM, run only the MCP container and point it to the remote IP:

docker run -d \
  --name kamailio-mcp-server \
  -p 8080:8080 \
  -e KAMAILIO_MCP_RPC_URL="http://<REMOTE_KAMAILIO_IP>:8080/jsonrpc" \
  -e KAMAILIO_MCP_DB_URL="postgresql+asyncpg://kamailio:password@<REMOTE_DB_IP>:5432/kamailio" \
  -e KAMAILIO_MCP_API_KEY="your_secret_api_key" \
  -e KAMAILIO_MCP_TRANSPORT="streamable-http" \
  kamailio-mcp:latest

Remote Access via Ngrok (No Public IP / Domain Required)

If your Kamailio server or MCP control plane is behind a local NAT, home router, or private cloud instance without a public IP or static domain, you can securely expose the MCP server using ngrok:

Step 1: Run Kamailio MCP in Network Mode (SSE or Streamable HTTP)

Start the server on 0.0.0.0:8080:

# Via CLI
kamailio-mcp serve --transport sse --host 0.0.0.0 --port 8080

# Or via Docker Compose
docker compose -f docker/docker-compose.yml up -d

Step 2: Install and Configure Ngrok

# Install ngrok CLI (Debian/Ubuntu)
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt-get update && sudo apt-get install ngrok

# Authenticate ngrok agent (sign up at https://dashboard.ngrok.com)
ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN

Step 3: Start HTTP Tunnel to Port 8080

ngrok http 8080

ngrok will output a public HTTPS forwarding URL:

Forwarding   https://a1b2c3d4.ngrok-free.app -> http://localhost:8080

Step 4: Connect Remote AI Clients or Web Apps

Point your remote MCP clients, web applications, or low-code portals to the ngrok URL:

• SSE Endpoint: https://a1b2c3d4.ngrok-free.app/sse

• Streamable HTTP Endpoint: https://a1b2c3d4.ngrok-free.app/mcp

[!SECURITY TIP] When exposing your server publicly via ngrok, enforce API key authentication by setting KAMAILIO_MCP_API_KEY=your_secret_key and passing Authorization: Bearer your_secret_key in request headers.

Architecture: Where to Run the MCP Server?

MCP Client Integration

1. Claude Desktop (Recommended)

Claude Desktop runs MCP servers locally over stdio without needing OAuth or public network exposure.

Edit your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kamailio": {
      "command": "kamailio-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "KAMAILIO_MCP_RPC_URL": "http://127.0.0.1:8080/jsonrpc",
        "KAMAILIO_MCP_DB_URL": "postgresql+asyncpg://kamailio:kamailio@localhost:5432/kamailio"
      }
    }
  }
}

2. Claude.ai (Web Remote MCP) & OAuth Troubleshooting

Couldn’t register with Kamalio MCP’s sign-in service. You can try again, or add an OAuth Client ID in the connector settings.

3. Cursor

Add to .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kamailio": {
      "command": "kamailio-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "KAMAILIO_MCP_RPC_URL": "http://127.0.0.1:8080/jsonrpc",
        "KAMAILIO_MCP_DB_URL": "postgresql+asyncpg://kamailio:kamailio@localhost:5432/kamailio"
      }
    }
  }
}

4. Gemini CLI / Antigravity / Codex CLI

For CLI-based AI agents, register the MCP server in your agent configuration (e.g. mcp_servers.json or command flags):

{
  "mcpServers": {
    "kamailio": {
      "command": "kamailio-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "KAMAILIO_MCP_RPC_URL": "http://127.0.0.1:8080/jsonrpc",
        "KAMAILIO_MCP_DB_URL": "postgresql+asyncpg://kamailio:kamailio@localhost:5432/kamailio"
      }
    }
  }
}

5. Cline (VS Code Extension)

In VS Code, open the Cline settings tab -> MCP Servers -> Edit Settings (cline_mcp_settings.json):

{
  "mcpServers": {
    "kamailio": {
      "command": "kamailio-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "KAMAILIO_MCP_RPC_URL": "http://127.0.0.1:8080/jsonrpc",
        "KAMAILIO_MCP_DB_URL": "postgresql+asyncpg://kamailio:kamailio@localhost:5432/kamailio"
      }
    }
  }
}

6. Continue (VS Code / JetBrains)

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "kamailio-mcp",
          "args": ["serve", "--transport", "stdio"],
          "env": {
            "KAMAILIO_MCP_RPC_URL": "http://127.0.0.1:8080/jsonrpc",
            "KAMAILIO_MCP_DB_URL": "postgresql+asyncpg://kamailio:kamailio@localhost:5432/kamailio"
          }
        }
      }
    ]
  }
}

Building Applications & Admin Portals Around Kamailio

kamailio-mcp provides structured schema exporters so external web apps (React, Vue, Next.js, Angular) can build dynamic UIs without hardcoding Kamailio parameters:

1. Get JSONSchema for Dynamic UI Forms:

   kamailio-mcp docs get-schema dispatcher

   Returns full parameter types, defaults, and descriptions for the dispatcher module.

2. Parse Config AST for Visual Routing Diagrams:

   kamailio-mcp cfg parse /etc/kamailio/kamailio.cfg

   Returns JSON parse tree of loaded modules, modparams, and route logic blocks.

3. Programmatically Generate Scenarios:

   kamailio-mcp cfg generate residential_pbx --param domain=sip.example.com --param db_driver=postgres

4. Lint & Validate Config Snippets:

   kamailio-mcp cfg lint /etc/kamailio/kamailio.cfg

Makefile Quick Reference

Run make or make help in the project root to view all shortcut tasks:

License

Apache-2.0 License.