Quickstart

This walks a newcomer from zero to a working OpenSIPS proxy managed by Claude in under 15 minutes. No SIP or OpenSIPS experience required.

If you know SIP already, you can skim — the essential parts are the MCP client setup and the first prompts sections.

---

Step 0 — What is this?

• OpenSIPS is a SIP proxy: it routes voice/video/messaging sessions.
• MCP (Model Context Protocol) lets an LLM (Claude) call real tools.
• This server gives Claude ~150 tools, 22 prompts, and 29 resources to generate configs, run diagnostics, manage routing, and observe runtime.

You end up with: "Claude, build me a residential SIP proxy and show me how it's doing." — and it just works.

---

Step 1 — Install (3 min)

Option A: Docker (fastest)

git clone https://github.com/OFFICERINGLLC/opensips-mcp-server.git
cd opensips-mcp-server
cp .env.example .env
docker compose -f docker/docker-compose.yml up -d

This brings up OpenSIPS + MySQL + the MCP server on one host.

Option B: pip (local dev)

python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
# Edit .env — at minimum set MI_URL to a reachable OpenSIPS, or leave
# defaults for Docker-compose mode.
opensips-mcp --transport stdio   # or --transport sse / streamable-http

---

Step 2 — Connect your MCP client (3 min)

The server speaks MCP. Pick your client:

Claude Desktop

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

{
  "mcpServers": {
    "opensips": {
      "command": "opensips-mcp",
      "args": ["--transport", "stdio"],
      "env": { "MI_URL": "http://localhost:8888/mi" }
    }
  }
}

Restart Claude Desktop. Look for the hammer/tool icon in the composer.

Claude Code (CLI)

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

Or add to .claude/settings.json:

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

Cursor

Edit ~/.cursor/mcp.json:

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

Continue (VS Code / JetBrains)

Edit ~/.continue/config.json:

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

SSE / streamable-http (any client, remote server)

Start the server in SSE mode:

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

Then point any MCP-speaking client at http://<host>:8700/sse. Put an auth proxy in front in production (see docs/security.md).

---

Step 3 — Your first prompts (5 min)

Open your MCP client and try, in order:

3a. "Are you connected?"

You: Run health_check on the OpenSIPS server. Tell me what's healthy and what isn't in plain English.

Claude will call the health_check tool. Expect a plain-language summary.

3b. "What can you do?"

You: What OpenSIPS scenarios can you generate? Show me the list and briefly describe each.

Claude will call cfg_list_scenarios.

3c. "Build me something"

You: I want a basic residential SIP proxy with authentication and NAT traversal. Generate the config for OpenSIPS 3.5, validate and lint it, then explain what each route block does.

Claude will chain cfg_generate → cfg_validate → cfg_lint → cfg_explain_route and give you a walkthrough. This is the "golden path" of this server.

3d. "Teach me something"

You: Explain how SIP registration works, assuming I only know basic networking.

Uses the teach_concept prompt or hands off to the opensips-teacher subagent if you're on Claude Code.

---

Step 4 — The right skill for the job

This server ships Claude Code skills — invoked with /skill-name:

Skill	When to use
/opensips-quickstart	New to OpenSIPS; pick a scenario + walk first config
/opensips-config-build	Build, edit, or refactor an opensips.cfg
/opensips-troubleshoot	Something is broken (calls, audio, registrations)
/opensips-migrate	Upgrade between OpenSIPS versions
/opensips-security-audit	Review posture / harden
/opensips-tool-chooser	"Which tool for X?"

And subagents — delegated specialists with their own tool sets:

Subagent	Role
opensips-architect	High-level design, scenario + module + capacity plan
opensips-config-author	Produces a validated, lint-clean config
opensips-incident-responder	Production incident triage (stabilise first)
opensips-migrator	Multi-hop version migrations
opensips-security-auditor	Hardening reports
opensips-teacher	Beginner-friendly lessons

In Claude Code: @opensips-architect help me design an SBC for 1000 CPS.

---

Step 5 — Where to go next

• Understand the tool surface: docs/tool-chooser.md
• When something breaks: docs/faq.md
• Config engine deep-dive: docs/cfg-engine.md
• Deploy to production: docs/deployment.md
• Harden for production: docs/security.md

---

"I got stuck" cheat sheet

Symptom	Fix
Claude can't see OpenSIPS tools	Restart the MCP client after editing config
mi_reachable: false	Check MI_URL in .env — OpenSIPS needs mi_http or mi_datagram module loaded
Permission denied: role 'readonly' lacks ...	Set ROLE=admin in .env (or acknowledge you wanted read-only)
"Unknown MI command"	Your OpenSIPS version may not support it — call mi_list_commands to see what's registered
Docker: ModuleNotFoundError	Run docker compose build --no-cache opensips-mcp

More at docs/faq.md.