Content
# 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](https://opensips.org). 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](https://www.opensips.org/events/Summit-2026Bucharest), Bucharest, April 28-30.*
```bash
# 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
```bash
# Install from source
pip install -e .
# For MySQL support
pip install -e ".[mysql]"
# For PostgreSQL support
pip install -e ".[postgres]"
```
### Configure
```bash
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
```bash
# 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):
```json
{
"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>
```bash
claude mcp add opensips -- opensips-mcp --transport stdio
```
Or edit `.claude/settings.json`:
```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`:
```json
{
"mcpServers": {
"opensips": { "command": "opensips-mcp", "args": ["--transport", "stdio"] }
}
}
```
</details>
<details>
<summary><b>Continue (VS Code / JetBrains)</b></summary>
`~/.continue/config.json`:
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "opensips-mcp",
"args": ["--transport", "stdio"]
}
}
]
}
}
```
</details>
<details>
<summary><b>Remote SSE / streamable-http</b></summary>
```bash
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](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:
```bash
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` | 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
```bash
# 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](CONTRIBUTING.md) for the full development guide.
## Documentation
**Start here:**
- **[Quickstart](docs/quickstart.md)** -- Zero to working proxy in 15 minutes (install → client setup → first prompts)
- **[Tool Chooser](docs/tool-chooser.md)** -- "Which tool should I use for X?" — map goals to tools
- **[FAQ / Troubleshooting](docs/faq.md)** -- Setup errors, runtime issues, common questions
**Reference:**
- [Architecture](docs/architecture.md) -- Layered design and component overview
- [Configuration Reference](docs/configuration.md) -- All environment variables and options
- [Security Model](docs/security.md) -- RBAC, validation, and audit logging
- [API Reference](docs/api-reference.md) -- Complete tools, resources, and prompts listing
- [Deployment Guide](docs/deployment.md) -- Docker and bare metal deployment
- [Config Engine](docs/cfg-engine.md) -- Scenario templates, linter, tuner, migration
- [Developer Guide](docs/development.md) -- 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](docs/examples/basic-usage.md)
- [Config Generation](docs/examples/config-generation.md)
- [Troubleshooting](docs/examples/troubleshooting.md)
- [Module Development](docs/examples/module-development.md)
## License
[Apache License 2.0](LICENSE) -- Copyright 2026 Officering LLC
