Opensips Mcp Server

OpenSIPS MCP Server

[](https://github.com/OFFICERINGLLC/opensips-mcp-server/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io) [](#testing) [](docs/cfg-engine.md) [](docs/api-reference.md)

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](docs/learn/kamailio-vs-opensips.md)) and a migration guide ([docs/learn/migrate-from-kamailio.md](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](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://:8700/sse. Put an auth proxy in front in production — see [docs/security.md](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](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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OpenSIPS
• Source: OpenSIPS/opensips-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.