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

<details> <summary><b>Claude Desktop</b></summary>

~/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"
      }
    }
  }
}

</details>

<details> <summary><b>Claude Code (CLI)</b></summary>

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. </details>

<details> <summary><b>Cursor</b></summary>

~/.cursor/mcp.json:

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

</details>

<details> <summary><b>Continue (VS Code / JetBrains)</b></summary>

~/.continue/config.json:

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

</details>

<details> <summary><b>Remote SSE / streamable-http</b></summary>

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. </details>

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

Examples

• Basic Usage
• Config Generation
• Troubleshooting
• Module Development

License

Apache License 2.0 -- Copyright 2026 Officering LLC