OpenSIPS MCP Server

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

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