OpenSIPS Server

CI Python 3.10+ License: Apache 2.0 MCP v1.27.0 Tests: 751 Scenarios: 25 Tools: 236

An AI-powered and shell-callable control plane for OpenSIPS. Connect any MCP-compatible AI client (Claude Desktop, Cursor, Cline, Continue, Cody) for natural-language operations — or use the same primitives via the opensips-mcp CLI for shell scripts, CI pipelines, and air-gapped operators.

Presented at OpenSIPS Summit 2026, Bucharest, April 28-30.

# AI client mode — connect any MCP-aware client
opensips-mcp serve

# CLI mode — no LLM required
opensips-mcp cfg list-scenarios
opensips-mcp cfg generate residential_pbx --param db_url=mysql://... --param domain=pbx.example.com
opensips-mcp cfg lint /etc/opensips/opensips.cfg --fail-on warning
opensips-mcp snapshot capture /var/lib/snapshots --label pre-deploy

Features

Why this over X?

Skeptical or looking for what this is NOT good for? Read docs/learn/limitations.md before adopting.

Highlights

• Full MI Coverage -- Execute any Management Interface command, list commands, gather statistics, and run health checks.
• Database Management -- CRUD operations for subscribers, dispatchers, dynamic routing, permissions, call center, load balancer, dialplan, and accounting tables.
• Configuration Engine -- Generate complete OpenSIPS configs from 8 scenario templates plus the m4/local.cfg override pattern, with a Kamailio-compatible WITH_* feature-flag composer that materialises a flat config (no #!ifdef nesting hell).
• Version-Aware Migration -- Declarative per-hop rule chain across 2.4 → 3.0 → 3.1 → 3.2 → 3.3 → 3.4 → 3.5 → 3.6 (7 fully-populated hops). Rewrites behaviour-preserving changes (MI command renames, AVP prefix drop, global param renames) and flags every manual step / silent-gotcha the engineer must handle by hand. Includes the painful 3.4 → 3.5 load_balancer_* → lb_* MI rename that silently breaks monitoring in 3.6. An eighth hop 3.6 → 4.0 is scaffolded with the MI renames anticipated in the 4.0 beta but emits an "advisory" warning until a stable 4.0 lands. (OpenSIPS skipped 3.7 entirely — the chain reflects the actual release line.)
• Semantic Linter -- 20+ rules checking module dependency graph, orphaned modparam, deprecated parameters, missing mf_process_maxfwd_header, anti-flood absence, NAT/rtpengine gaps, and production readiness.
• Capacity Tuner (PGTune for SIP) -- Describe your workload (role + cores + RAM + CPS + NAT + TLS + HA), get a paste-ready override snippet with a # why: comment on every line.
• Module Catalog + Explain -- Machine-readable module metadata powers a kubectl explain-style lookup for directives, modparams, script functions, pseudo-variables, and MI commands (with rename history).
• Diagnostics -- Process lists, memory stats, TCP connections, uptime, tracing, and comprehensive health checks.
• Security -- RBAC with readonly/admin roles, input validation, HA1 digest generation, config audit, Pike anti-flood management, and structured audit logging.
• Version Support -- 2.4 → 3.6 fully rule-backed; one anticipatory 3.6 → 4.0 hop with master-branch MI renames (advisory until 4.0 stable). Runtime version strategies for 3.4 and 3.6 (production-ready) plus a 4.0 strategy flagged as experimental.
• Docker Ready -- 7 pre-built Docker scenarios and a full-stack compose for instant deployment.

Quick Start

pip install

# Install from source
pip install -e .

# For MySQL support
pip install -e ".[mysql]"

# For PostgreSQL support
pip install -e ".[postgres]"

Configure

cp .env.example .env
# Edit .env with your OpenSIPS MI URL and database connection

Key environment variables:

Run

# stdio transport (for Claude Desktop, Cursor, etc.)
opensips-mcp

# SSE transport (for web-based clients)
opensips-mcp --transport sse --host 0.0.0.0 --port 8080

# Streamable HTTP transport
opensips-mcp --transport streamable-http --host 0.0.0.0 --port 8080

MCP Client Integration

{
  "mcpServers": {
    "opensips": {
      "command": "opensips-mcp",
      "env": {
        "OPENSIPS_MCP_MI_URL": "http://your-opensips:8888/mi",
        "OPENSIPS_MCP_DB_URL": "mysql+asyncmy://opensips:opensipsrw@localhost/opensips"
      }
    }
  }
}

claude mcp add opensips -- opensips-mcp --transport stdio

{
  "mcpServers": {
    "opensips": { "command": "opensips-mcp", "args": ["--transport", "stdio"] }
  }
}

{
  "mcpServers": {
    "opensips": { "command": "opensips-mcp", "args": ["--transport", "stdio"] }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "opensips-mcp",
          "args": ["--transport", "stdio"]
        }
      }
    ]
  }
}

opensips-mcp --transport sse --host 0.0.0.0 --port 8700

Docker Quick Start

Start OpenSIPS, MySQL, and the MCP server with a single command:

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

This brings up:

• opensips -- OpenSIPS 3.6 with MI HTTP on port 8888
• mysql -- MySQL 8.0 with the OpenSIPS schema
• opensips-mcp -- MCP server on port 8080 (streamable-http transport)

See docs/deployment.md for production deployment guidance.

MCP Tools

MI Commands

• mi_execute -- Execute any MI command
• mi_list_commands -- List available MI commands
• get_statistics -- Retrieve runtime statistics
• health_check -- Comprehensive health check

User Location

• ul_show_contacts -- Show registered contacts for an AOR
• ul_dump -- Dump all registered users
• ul_add_contact -- Add a contact binding
• ul_remove_contact -- Remove a contact binding

Dialog Management

• dlg_list -- List active dialogs
• dlg_end -- Terminate a dialog
• dlg_get_profiles -- Get dialog profile sizes
• dlg_push_var -- Set a dialog variable

Subscriber Management

• subscriber_list -- List subscribers (with pagination)
• subscriber_get -- Get subscriber by ID
• subscriber_create -- Create a new subscriber
• subscriber_update -- Update subscriber fields
• subscriber_delete -- Delete a subscriber

Dispatcher (Load Balancing)

• dispatcher_list_db -- List dispatcher destinations
• dispatcher_add -- Add a destination
• dispatcher_update -- Update a destination
• dispatcher_remove -- Remove a destination

Dynamic Routing (full CRUD + reload)

• drouting_list_rules, drouting_add_rule, drouting_update_rule, drouting_delete_rule
• drouting_list_gateways, drouting_add_gateway, drouting_update_gateway, drouting_delete_gateway
• drouting_list_carriers, drouting_add_carrier, drouting_update_carrier, drouting_delete_carrier

Dialplan (number translation)

• dialplan_list_rules, dialplan_add_rule, dialplan_update_rule, dialplan_delete_rule
• dialplan_reload, dialplan_translate

Carrier Routing & LCR

• carrierroute_reload, carrierroute_dump, carrierroute_activate_host, carrierroute_deactivate_host, carrierroute_replace_host
• lcr_dump, lcr_reload

B2BUA (back-to-back, SBC, SCA)

• b2b_list_sessions, b2b_list_entities, b2b_terminate, b2b_bridge, b2b_trigger_scenario, b2b_sca_list
• topology_hiding_list

Presence / PUA / BLF / MWI

• presence_list_subscriptions, presence_refresh_watchers, presence_cleanup
• pua_list_publications, pua_publish

UAC / Upstream Registrations

• uac_reg_list, uac_reg_reload, uac_reg_enable, uac_reg_disable, uac_reg_force_register

Mid-Registrar

• mid_registrar_dump, mid_registrar_update

NAT Helper

• nathelper_enable_ping, nathelper_stats

Event Interface (flatstore, rabbitmq, json, etc.)

• event_list, event_list_subscribers, event_subscribe

Stateless (SL)

• sl_stats

AVP Operations

• avp_get, avp_set, avp_delete

Load Balancer

• lb_list -- List load balancer destinations
• lb_reload -- Reload LB table
• lb_set_status -- Enable/disable a destination
• lb_resize -- Resize a resource

Call Center

• cc_list_queue -- List call center queue
• cc_list_agents -- List agents
• cc_agent_login -- Login/logout an agent
• cc_reload_tool -- Reload call center config
• cc_status -- Call center statistics

Permissions

• address_list -- List address permissions
• address_add -- Add an address entry
• address_remove -- Remove an address entry

Security

• pike_list_blocked -- List Pike-blocked IPs
• pike_unblock_ip -- Unblock an IP
• security_generate_ha1 -- Generate HA1 digests
• security_audit_config -- Audit a configuration

RTPEngine

• rtpengine_show -- Show RTPEngine status
• rtpengine_enable -- Enable/disable an RTPEngine instance
• rtpengine_reload -- Reload RTPEngine config

Rate Limiting

• ratelimit_status -- Show rate limit pipes
• ratelimit_reset -- Reset a rate limit pipe

Cluster

• cluster_status -- Cluster node status
• cluster_topology -- Cluster topology
• cluster_send_command -- Send a cluster broadcast command

Tracing

• trace_control -- Enable/disable SIP tracing
• trace_start_live -- Start live SIP trace

Registrar

• registrar_stats -- Registrar statistics

Accounting

• acc_query_cdrs -- Query CDR records
• acc_query_missed -- Query missed call records

Diagnostics

• get_process_list -- OpenSIPS process list
• get_memory_stats -- Shared/private memory stats
• get_uptime -- Server uptime
• get_tcp_connections -- Active TCP connections
• opensips_version -- OpenSIPS version info

Configuration Engine — generation

• cfg_generate -- Generate config from a scenario template
• cfg_generate_iterative -- Generate and iteratively validate
• cfg_list_scenarios / cfg_get_scenario_params -- Scenario catalog
• cfg_start_session / cfg_generate_m4 / cfg_preprocess / cfg_dry_run / cfg_save_session -- m4 / local.cfg override pattern
• cfg_list_flags / cfg_compose_flags / cfg_build_from_flags -- Kamailio-compatible WITH_* feature-flag composer (produces a flat config with only enabled branches materialised)

Configuration Engine — understanding

• cfg_parse -- Parse config and extract structure
• cfg_validate -- Validate with the opensips -C -f binary
• cfg_explain -- kubectl explain-style inline reference for any module / modparam / function / $pv / global / MI command
• cfg_explain_route -- Analyse a specific route block
• cfg_list_modules -- Module catalog (filter by version or category)

Configuration Engine — editing

• cfg_diff -- Unified diff between two configurations
• cfg_diff_reference -- Diff against the reference scenario template to see what's "custom"
• cfg_edit -- Apply a natural-language edit and show the diff
• cfg_add_module -- Add a module (with optional modparams) into an existing cfg
• cfg_optimize -- Quick heuristic suggestions

Configuration Engine — linting & tuning

• cfg_lint -- Run 20+ semantic lint rules (dependency gaps, deprecated params, missing anti-flood, etc.)
• cfg_list_lint_rules -- Rule catalog
• cfg_tune -- PGTune-style capacity tuner: describe workload → get override snippet with # why: comments

Configuration Engine — version migration

• cfg_list_versions -- Supported versions and hop chain (2.4 → 3.0 → 3.1 → 3.2 → 3.3 → 3.4 → 3.5 → 3.6 fully populated; one anticipatory 3.6 → 4.0 hop)
• cfg_check_compat -- Check a config for modules unavailable in a target version
• cfg_migrate_plan -- Terraform-plan-style dry-run: report every rewrite and every manual step
• cfg_migrate -- Apply the migration, emit a unified diff, validate the result

MCP Resources

MCP Prompts

Architecture

+------------------+     +-------------------+     +------------------+
|   MCP Client     |     |  OpenSIPS MCP     |     |    OpenSIPS      |
|  (Claude, etc.)  |<--->|  Server           |<--->|  (MI HTTP)       |
+------------------+     |                   |     +------------------+
                         |  +-------------+  |
                         |  | Tools (94)  |  |     +------------------+
                         |  +-------------+  |     |    Database      |
                         |  | Resources   |  |<--->|  (MySQL/PG/      |
                         |  +-------------+  |     |   SQLite)        |
                         |  | Prompts     |  |     +------------------+
                         |  +-------------+  |
                         |  | Config Eng. |  |
                         |  +-------------+  |
                         |  | Security    |  |
                         |  +-------------+  |
                         +-------------------+

Layers:
  MCP (FastMCP)  ->  Service (Tools/Resources/Prompts)
                 ->  Infrastructure (MI Client, DB, Config Engine)
                 ->  Version (3.4 / 3.6 strategies)
                 ->  Security (RBAC, Validation, Audit)

Supported OpenSIPS Versions

OpenSIPS jumped from 3.6 directly to 4.0 — there was no 3.7 release. The migrator chain reflects the actual release line (8 hops total: 7 fully populated to 3.6, plus 1 anticipatory hop to 4.0).

Development

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Test
make test

# Lint and format
make lint
make format
make type-check

See CONTRIBUTING.md for the full development guide.

Documentation

Start here:

• Quickstart -- Zero to working proxy in 15 minutes (install → client setup → first prompts)
• Tool Chooser -- "Which tool should I use for X?" — map goals to tools
• FAQ / Troubleshooting -- Setup errors, runtime issues, common questions

Reference:

• Architecture -- Layered design and component overview
• Configuration Reference -- All environment variables and options
• Security Model -- RBAC, validation, and audit logging
• API Reference -- Complete tools, resources, and prompts listing
• Deployment Guide -- Docker and bare metal deployment
• Config Engine -- Scenario templates, linter, tuner, migration
• Developer Guide -- Adding tools, templates, and testing

Claude Code skills and subagents (in .claude/skills/ and .claude/agents/):

• Skills: /opensips-quickstart, /opensips-config-build, /opensips-troubleshoot, /opensips-migrate, /opensips-security-audit, /opensips-tool-chooser
• Subagents: opensips-architect, opensips-config-author, opensips-incident-responder, opensips-migrator, opensips-security-auditor, opensips-teacher

Examples

• Basic Usage
• Config Generation
• Troubleshooting
• Module Development

License

Apache License 2.0 -- Copyright 2026 Officering LLC