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

| Category | Count | Description | |----------|-------|-------------| | Tools | 236 | MI, DB CRUD, cfg engine, migration, linting, tuning, diagnostics, security, B2BUA, presence, events, snapshots, benchmarks, RBAC, observability stack generator (Grafana + Prometheus + provisioning + monitoring docker-compose) | | Scenarios | 25 | From class-4 SBC and residential PBX to IMS Cx with HSS interop, STIR/SHAKEN, SIPREC, MSRP, RADIUS auth, qrouting, RTT accessibility | | Prompts | 22 | Config building, migration, troubleshoot, security audit, education | | Operator-facing docs | 15 | SIP primer, error-code decoder, annotated cfg tour, ngrep/sngrep, end-to-end PBX tutorial, HA failover, NAT decision tree, TLS-from-scratch, post-deploy smoke test, IMS Cx with open5gs, compliance positioning, observability stack, Kamailio comparison + migration, limitations, more | | Compliance frameworks addressed | 8 | HIPAA, GDPR/CCPA, SOC 2, PCI DSS, FCC § 13.114 (E911), STIR/SHAKEN, RFC 4103 RTT, NENA i3 | | Tests | 751 | Drift-prevention regression markers for every audit finding | | Skills | 6 | Claude Code slash commands | | Subagents | 6 | Claude Code orchestration roles |

Why this over X?

| If you're considering... | This project gives you | |---|---| | Hand-written m4 templates | A typed scenario library + auto-discovered knobs + a linter that catches what opensips -C misses | | opensips-cli | Same primitives + 25 scenario templates + the migration engine + drift snapshots + 15 operator-facing docs | | Kamailio (kamctl / kamcli) | An honest comparison (docs/learn/kamailio-vs-opensips.md) and a migration guide (docs/learn/migrate-from-kamailio.md) | | Twilio / Telnyx / Bandwidth | Self-hosted control over your SIP — at the cost of operating it yourself | | DIY without an LLM | The CLI is the same code path; nothing requires AI | | DIY without a CLI | Same primitives via MCP for any AI client |

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:

| Variable | Default | Description | |----------|---------|-------------| | OPENSIPS_MCP_MI_URL | http://127.0.0.1:8888/mi | OpenSIPS MI HTTP endpoint | | OPENSIPS_MCP_DB_URL | sqlite+aiosqlite:///opensips.db | Database connection string | | OPENSIPS_MCP_VERSION | 3.6 | Target OpenSIPS runtime version (3.4 or 3.6) | | OPENSIPS_MCP_TRANSPORT | stdio | MCP transport (stdio, sse, streamable-http) | | OPENSIPS_MCP_ROLE | readonly | RBAC role (readonly, admin). Defaults to least-privileged; set to admin only when write / MI-execute access is required. | | OPENSIPS_MCP_LOG_LEVEL | INFO | Logging level | | OPENSIPS_MCP_HOST | 127.0.0.1 | Bind address for network transports | | OPENSIPS_MCP_PORT | 8080 | Listen port for network transports | | OPENSIPS_MCP_API_KEY | (empty) | Optional API key for authentication | | OPENSIPS_MCP_OPENSIPS_BIN | /usr/sbin/opensips | Path to opensips binary for config validation | | OPENSIPS_MCP_READ_ONLY | false | Force read-only mode regardless of role |

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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "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 Code (CLI)

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

Or edit .claude/settings.json:

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

The project ships skills and subagents in .claude/ — Claude Code picks them up automatically when run inside the repo.

Cursor

~/.cursor/mcp.json:

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

Continue (VS Code / JetBrains)

~/.continue/config.json:

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

Remote SSE / streamable-http

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

Point any MCP-speaking client at http://<host>:8700/sse. Put an auth proxy in front in production — see docs/security.md and docker/nginx/ for a working config.

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

| URI | Description | |-----|-------------| | opensips://system/version | OpenSIPS version information | | opensips://system/uptime | Server uptime | | opensips://system/processes | Running processes | | opensips://system/memory | Memory usage | | opensips://stats/all | All runtime statistics | | opensips://modules/list | Available modules | | opensips://modules/{name} | Module documentation | | opensips://docs/mi/{command} | MI command documentation | | opensips://templates/list | Available config templates | | opensips://templates/{scenario} | Scenario template source | | opensips://scenarios/list | Deployment scenario catalog | | opensips://scenarios/{name} | Scenario detail and Docker config | | opensips://db/subscribers | Subscriber table snapshot | | opensips://db/dispatchers | Dispatcher table snapshot |

MCP Prompts

| Prompt | Description | |--------|-------------| | build_config | Interactive OpenSIPS configuration builder | | optimize_performance | Performance tuning advisor | | design_architecture | SIP architecture designer | | troubleshoot_calls | Call failure troubleshooting guide | | troubleshoot_registration | Registration failure troubleshooting | | explain_error | SIP/OpenSIPS error explainer | | security_audit | Security configuration auditor | | teach_concept | SIP/VoIP concept educator | | explain_sip_ladder | SIP ladder diagram analyzer | | explain_route | OpenSIPS route block explainer | | debug_sip_message | SIP message parser and debugger | | plan_capacity | SIP capacity planning advisor | | write_module | OpenSIPS C module development guide | | migrate_version | Version migration assistant (natural-language plan) | | migrate_version_auto | Automated plan + apply workflow driving cfg_migrate_plan / cfg_migrate | | compare_modules | Module comparison guide |

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

| Version | Status | Notes | |---------|--------|-------| | 2.4 | Migration source | Fully rule-backed source for cfg_migrate | | 3.0–3.5 | Migration source | Each hop has fully-populated rule sets | | 3.4 | Runtime supported | LTS — full MI and DB coverage | | 3.6 | Runtime default + migration target | Latest stable LTS (3.6.4 as of 2026-04) | | 4.0 | Anticipated migration target / experimental runtime | One advisory hop with master-branch MI renames; rules not yet validated against a stable build |

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