Configuration Reference

April 28, 2026 · View on GitHub

All settings are configured through environment variables with the OPENSIPS_MCP_ prefix. You can also place them in a .env file in the working directory.

Environment Variables

Variable	Type	Default	Description
`OPENSIPS_MCP_MI_URL`	string	`http://127.0.0.1:8888/mi`	OpenSIPS Management Interface HTTP endpoint URL
`OPENSIPS_MCP_DB_URL`	string	`sqlite+aiosqlite:///opensips.db`	SQLAlchemy async database URL
`OPENSIPS_MCP_VERSION`	string	`3.6`	Target OpenSIPS version (`3.4`, `3.6`, or `4.0`)
`OPENSIPS_MCP_TRANSPORT`	string	`stdio`	MCP transport type: `stdio`, `sse`, or `streamable-http`
`OPENSIPS_MCP_LOG_LEVEL`	string	`INFO`	Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`OPENSIPS_MCP_ROLE`	string	`admin`	RBAC role: `readonly` or `admin`
`OPENSIPS_MCP_API_KEY`	string	(empty)	Optional API key for client authentication
`OPENSIPS_MCP_OPENSIPS_BIN`	string	`/usr/sbin/opensips`	Path to the OpenSIPS binary (used for `cfg_validate`)
`OPENSIPS_MCP_DOCS_PATH`	string	(empty)	Path to local OpenSIPS documentation files
`OPENSIPS_MCP_READ_ONLY`	bool	`false`	Force read-only mode regardless of role setting
`OPENSIPS_MCP_HOST`	string	`127.0.0.1`	Bind address for SSE and streamable-http transports
`OPENSIPS_MCP_PORT`	int	`8080`	Listen port for SSE and streamable-http transports

Transport Options

stdio (default)

Standard input/output transport. Used by MCP clients that launch the server as a subprocess (Claude Desktop, Cursor, etc.).

opensips-mcp
# or
opensips-mcp --transport stdio

No network configuration needed. The MCP client manages the process lifecycle.

SSE (Server-Sent Events)

Network transport using HTTP with Server-Sent Events for server-to-client streaming.

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

The server listens on the specified host and port. Clients connect via HTTP.

Streamable HTTP

Bidirectional HTTP transport. This is the recommended transport for Docker deployments and multi-client scenarios.

opensips-mcp --transport streamable-http --host 0.0.0.0 --port 8080

Database Backends

SQLite (default)

Suitable for development and single-node deployments. No additional packages required.

OPENSIPS_MCP_DB_URL=sqlite+aiosqlite:///opensips.db

MySQL

Recommended for production. Install the MySQL extra:

pip install -e ".[mysql]"

OPENSIPS_MCP_DB_URL=mysql+asyncmy://opensips:opensipsrw@localhost:3306/opensips

PostgreSQL

Alternative production backend. Install the PostgreSQL extra:

pip install -e ".[postgres]"

OPENSIPS_MCP_DB_URL=postgresql+asyncpg://opensips:CHANGE_ME_PASSWORD@localhost:5432/opensips

Security Configuration

Role-Based Access Control

Set the role to control what operations are permitted:

# Read-only access (default): no writes, no MI commands that modify state
OPENSIPS_MCP_ROLE=readonly

# Full access: all readonly permissions plus write operations, MI execution,
# config generation, and process management. Only enable when required.
OPENSIPS_MCP_ROLE=admin

See security.md for the complete permission matrix.

Read-Only Override

Force read-only mode regardless of the role setting:

OPENSIPS_MCP_READ_ONLY=true

API Key

Set an API key to require authentication from MCP clients:

OPENSIPS_MCP_API_KEY=your-secret-key-here

Example `.env` File

# OpenSIPS connection
OPENSIPS_MCP_MI_URL=http://opensips.internal:8888/mi
OPENSIPS_MCP_DB_URL=mysql+asyncmy://opensips:CHANGE_ME_PASSWORD@db.internal:3306/opensips

# Server settings
OPENSIPS_MCP_VERSION=3.6
OPENSIPS_MCP_TRANSPORT=streamable-http
OPENSIPS_MCP_HOST=0.0.0.0
OPENSIPS_MCP_PORT=8080
OPENSIPS_MCP_LOG_LEVEL=INFO

# Security
OPENSIPS_MCP_ROLE=readonly
OPENSIPS_MCP_API_KEY=my-secure-api-key

CLI Options

The opensips-mcp command accepts options that override environment variables:

Usage: opensips-mcp [OPTIONS]

  Run the OpenSIPS MCP Server.

Options:
  --transport [stdio|sse|streamable-http]
                                  MCP transport type
  --host TEXT                     Bind address for network transports
  --port INTEGER                  Listen port for network transports
  --log-level [DEBUG|INFO|WARNING|ERROR]
                                  Logging level
  --help                          Show this message and exit.

CLI options take precedence over environment variables. Environment variables take precedence over defaults.