@calltelemetry/cisco-ris-mcp

MCP server for Cisco CUCM Real-time Information Service (RIS) and PerfMon SOAP APIs.

Built by Call Telemetry — realtime tools for Cisco Collaboration.

An MCP server that gives AI assistants direct access to Cisco CUCM device registration status, performance counters, and cluster health — via the RIS and PerfMon SOAP APIs.

You ask about your cluster in plain language. The LLM queries RIS and PerfMon for you.

Troubleshooting & Triage

• "Are all phones registered? Which ones aren't?"
• "Find all phones on subnet 10.1.5.x — are any unregistered?"
• "Is SEP001122334455 registered? What node is it on? What's its IP?"
• "Show me all rejected phones and their rejection reasons"
• "Which CUCM node has the most unregistered devices?"

Capacity & Performance

• "Show me call volume over the last 5 minutes"
• "How many MTP and transcoder resources are available?"
• "Are we running low on conference bridge resources?"
• "What's the CPU utilization on the publisher?"
• "Monitor SIP trunk call activity for the next 2 minutes"

Health & Situational Awareness

• "Is the cluster healthy?"
• "Give me a registration breakdown by protocol — how many SIP vs SCCP?"
• "How many Jabber clients are connected via MRA?"
• "Are any CTI applications connected? What's their status?"
• "Compare registration counts to what CUCM thinks is registered via PerfMon"

Usage Collection & Trending

• "Monitor call volume for the next 5 minutes and show me the trend"
• "Track registration changes — are phones dropping off?"
• "Collect CPU samples every 10 seconds and graph the usage"
• "Start monitoring SIP trunk activity while I make test calls"
• "How is MTP utilization trending during business hours?"

Results include Unicode sparklines for visual trending:

CallsActive      ▁▁▂▃▅▇█▇▅▃▂▁  min=0 max=47 avg=18.3
CallsCompleted   ▁▂▃▄▅▆▇█▇▇██  delta=234 rate=3.9/s
RegisteredPhones ████████████▇  min=847 max=850 avg=849

Inventory & Reporting

• "How many phones are registered by model/firmware?"
• "List all registered hardware phones and their IPs"
• "What PerfMon counters are available on this cluster?"
• "Show me all instances of Cisco SIP trunk counters"

Installation

No install required — npx downloads and runs automatically:

npx @calltelemetry/cisco-ris-mcp

What It Does

• Device registration — Query real-time phone, gateway, and CTI device status with wildcard search, model/protocol filtering, and auto-pagination across cluster nodes
• Performance counters — Snapshot or continuously monitor PerfMon counters (calls active, registration counts, SIP stats, CPU) with built-in presets for common scenarios
• Cluster health — Single-call health check combining RIS device registration + PerfMon counters with configurable threshold alerts

Tools

Configuration

Environment Variables

All credentials can also be passed per-tool-call via cucm_host, cucm_username, cucm_password, cucm_port parameters — useful for querying multiple clusters in a single session.

Counter Presets

Presets select a curated set of counters for common monitoring scenarios:

Tool Examples

All examples below are from a live CUCM 15.0 cluster.

phone_summary — Registration overview

Returns aggregate counts by model, protocol, and cluster node. Ideal for dashboards.

Input:

{ "summaryOnly": true }

Output:

{
  "totalDevices": 1,
  "registered": 1,
  "unregistered": 0,
  "registrationRate": 100,
  "byModel": {
    "SCCP75.9-4-2SR4-3S": { "registered": 1, "unregistered": 0 }
  },
  "byProtocol": {
    "SCCP": { "registered": 1, "unregistered": 0 }
  },
  "byNode": [
    { "name": "cucm15-pub", "registered": 1, "unregistered": 0, "total": 1 }
  ]
}

device_status — Search specific devices

Query device registration by name pattern with full per-device detail.

Input:

{ "query": "SEP*" }

Output (all fields from CUCM SOAP response, strongly typed):

{
  "totalDevicesFound": 1,
  "cmNodes": [
    {
      "name": "cucm15-pub",
      "returnCode": "Ok",
      "devices": [
        {
          "name": "SEP0022905C7710",
          "ipAddress": "10.0.0.178",
          "ipAddrType": "ipv4",
          "ipAttribute": "AdministrativeAndSignaling",
          "description": "Auto 1000 7975 Phone3",
          "dirNumber": "1000-Registered",
          "status": "Registered",
          "statusReason": 0,
          "protocol": "SCCP",
          "deviceClass": "Phone",
          "model": 437,
          "product": 336,
          "httpd": "Yes",
          "registrationAttempts": 1,
          "isCtiControllable": true,
          "loginUserId": "",
          "numOfLines": 1,
          "linesStatus": [
            { "directoryNumber": "1000", "status": "Registered" }
          ],
          "activeLoadId": "SCCP75.9-4-2SR4-3S",
          "inactiveLoadId": "",
          "downloadStatus": "Unknown",
          "downloadFailureReason": "",
          "downloadServer": "",
          "timeStamp": 1773835197
        }
      ]
    }
  ]
}

registration_health — Cluster health check

Single call combining RIS registration data + PerfMon counters with threshold-based alerts.

Input:

{}

Output:

{
  "overall": {
    "registrationRate": 100,
    "totalDevices": 1,
    "registered": 1,
    "unregistered": 0
  },
  "nodes": [
    { "name": "cucm15-pub", "registrationRate": 100, "registered": 1, "unregistered": 0 }
  ],
  "counters": {
    "CallsActive": 0,
    "RegisteredHardwarePhones": 1,
    "CallManagerHeartBeat": 4958,
    "InitializationState": 100
  },
  "alerts": []
}

An empty alerts array means the cluster is healthy. When thresholds are breached (e.g., registration rate drops below 90%), alerts describe the condition.

counter_snapshot — One-shot counter read

Read PerfMon counters using a preset or custom object/counter list.

Input (registration preset):

{ "preset": "registration" }

Output:

{
  "object": "Cisco CallManager",
  "host": "10.0.0.1",
  "counters": [
    { "name": "RegisteredHardwarePhones", "value": 1, "cStatus": 1 },
    { "name": "RegisteredOtherStationDevices", "value": 0, "cStatus": 1 },
    { "name": "PartiallyRegisteredPhone", "value": 0, "cStatus": 1 }
  ]
}

Input (call processing preset):

{ "preset": "call_processing" }

Output:

{
  "object": "Cisco CallManager",
  "host": "10.0.0.1",
  "counters": [
    { "name": "CallsActive", "value": 0, "cStatus": 1 },
    { "name": "CallsAttempted", "value": 0, "cStatus": 1 },
    { "name": "CallsCompleted", "value": 0, "cStatus": 1 }
  ]
}

counter_list — Discover available counters

List all PerfMon objects and their counters on the cluster.

Input:

{}

Output (truncated):

[
  {
    "objectName": "Cisco CAR DB",
    "multiInstance": true,
    "counters": ["CARDBSpaceUsed", "CARTempDBSpaceUsed", "FreeSharedMemory", "RootDBSpaceUsed", "UsedSharedMemory"]
  },
  {
    "objectName": "Cisco CallManager",
    "multiInstance": false,
    "counters": ["CallsActive", "CallsAttempted", "CallsCompleted", "RegisteredHardwarePhones", "...120 more"]
  },
  {
    "objectName": "Cisco SIP Stack",
    "multiInstance": false,
    "counters": ["InviteIns", "InviteOuts", "RegisterIns", "ByeIns", "...150 more"]
  }
]

counter_instances — List multi-instance object entries

Discover which devices, lines, or resources exist as instances of a PerfMon object.

Input:

{ "object": "Cisco Phones" }

Output:

{
  "object": "Cisco Phones",
  "instances": ["SEP0022905C7710"]
}

counter_monitor_start — Background monitoring

Start continuous counter collection at a configurable interval. Returns a monitorId for retrieving results.

Input:

{
  "object": "Cisco CallManager",
  "counters": ["CallsActive", "CallsAttempted", "CallsCompleted"],
  "intervalMs": 10000,
  "maxSamples": 100
}

Output:

{
  "monitorId": "mon-1710756000-abc123",
  "status": "running",
  "object": "Cisco CallManager",
  "counters": ["CallsActive", "CallsAttempted", "CallsCompleted"],
  "intervalMs": 10000,
  "maxSamples": 100,
  "message": "Monitor started. Use counter_monitor_results to read samples, counter_monitor_stop to end."
}

counter_monitor_results — Read accumulated statistics

Retrieve samples from a running or completed monitor with computed statistics per counter.

Input:

{ "monitorId": "mon-1773846059140-5md4o5" }

Output (includes Unicode sparklines for visual trending):

{
  "monitorId": "mon-1773846059140-5md4o5",
  "status": "running",
  "samplesCollected": 10,
  "maxSamples": 100,
  "durationMs": 100000,
  "stats": [
    {
      "name": "CallsActive",
      "type": "gauge",
      "sparkline": "▁▂▃▅▇█▇▅▃▁",
      "min": 0, "max": 47, "avg": 18.3,
      "delta": 0, "rate": 0, "latest": 2
    },
    {
      "name": "CallsCompleted",
      "type": "counter",
      "sparkline": "▁▂▃▄▅▆▆▇▇█",
      "min": 1200, "max": 1438, "avg": 1319,
      "delta": 238, "rate": 2.38, "latest": 1438
    }
  ]
}

Statistics use actual timestamps (not assumed intervals) for rate calculation. Counters are classified as:

• gauge (CallsActive, RegisteredHardwarePhones) — min/max/avg are meaningful
• counter (CallsCompleted, CallsAttempted) — delta and rate (per second) are meaningful

Results remain available for 30 minutes after a monitor completes or is stopped.

counter_monitor_stop — Stop and finalize

Stops a running monitor, closes the PerfMon session on CUCM, and returns final statistics.

Input:

{ "monitorId": "mon-1773846059140-5md4o5" }

Output:

{
  "monitorId": "mon-1773846059140-5md4o5",
  "status": "completed",
  "samplesCollected": 10,
  "durationMs": 100000,
  "stats": [
    { "name": "CallsActive", "type": "gauge", "sparkline": "▁▂▃▅▇█▇▅▃▁", "min": 0, "max": 47, "avg": 18.3, "latest": 2 },
    { "name": "CallsCompleted", "type": "counter", "sparkline": "▁▂▃▄▅▆▆▇▇█", "delta": 238, "rate": 2.38, "latest": 1438 }
  ]
}

MCP Configuration

Claude Code (one-liner)

claude mcp add cucm_ris \
  -e CUCM_HOST=cucm-pub.example.com \
  -e CUCM_USERNAME=admin \
  -e CUCM_PASSWORD=secret \
  -- npx @calltelemetry/cisco-ris-mcp

mcp.json

{
  "mcpServers": {
    "cucm-ris": {
      "command": "npx",
      "args": ["@calltelemetry/cisco-ris-mcp"],
      "env": {
        "CUCM_HOST": "cucm-pub.example.com",
        "CUCM_USERNAME": "admin",
        "CUCM_PASSWORD": "secret"
      }
    }
  }
}

Architecture

• SOAP client — Wraps the RIS selectCmDevice and PerfMon perfmonCollectCounterData / perfmonListCounter SOAP endpoints
• Rate limiter — Prevents overloading CUCM with concurrent RIS/PerfMon requests
• TTL cache — Caches counter metadata and device queries to reduce SOAP round-trips
• Background monitoring — In-memory poll loop for counter_monitor_* tools with automatic sample collection
• Structured errors — All failures return typed error objects with CUCM-specific context

Development

yarn install        # Install dependencies
yarn build          # Build with Vite
yarn dev            # Watch mode
yarn typecheck      # Type check
yarn lint           # Lint
yarn test           # Run tests
yarn validate       # typecheck + lint + test

Related

License

MIT