@ucm-control-kit/mcp

Audit, monitor, repair and voice-control Grandstream UCM phone systems from any AI agent.

Quick start · What it does · Use it from your AI tool · Voice · Multi-site · Security

Organisations with many branches run one Grandstream UCM and dozens of desk phones. When a branch goes quiet, someone usually opens the UCM web UI, looks for the extension, and starts guessing.

This kit replaces that guessing with one set of tools. You can use them from a terminal, from any MCP-capable AI assistant, from an Agent Skill, or by voice.

• Direct to the PBX. It talks to the UCM's own HTTPS API. No cloud relay, no agents on the phones.

• Safe by default. Every tool that rings phones or changes settings needs an explicit confirmation and an allow-listed action.

• Grounded in a real network. The matching and diagnosis rules come from a live 44-branch retail network, and every published example is anonymised.

What it does

Related MCP server: Systems Manager

Quick start

1. Create an API user on the UCM. Go to Integrations → API Configuration → API Settings (New):

   • turn on Enable API;

   • add a user and tick the permissions you need;

   • Save.

   Turning on that user's IP allowlist is recommended.

2. Run the CLI:

export UCM_HOST=192.168.1.10:8089 UCM_USER=api_user   # password is prompted
npx @ucm-control-kit/cli status
npx @ucm-control-kit/cli audit              # which permissions are missing?
npx @ucm-control-kit/cli extensions --offline
npx @ucm-control-kit/cli reconcile --registry sites.json
npx @ucm-control-kit/cli calls --period week --registry sites.json --csv calls.csv
UCM_ALLOW_WRITES=dialExtension npx @ucm-control-kit/cli call 1001 1002

A site registry is plain JSON; see examples/sites.example.json:

[{ "id": "harbour", "name": "Harbour Road", "aliases": ["Harbour"], "extension": "1001", "subnet": "10.10.1.0/24" }]

No hardware to hand? pnpm demo starts a fake UCM plus the voice console. Every command works against it.

Use it from your AI tool

The MCP server exposes the tools to any MCP client. For example, in Claude Code:

claude mcp add ucm -e UCM_HOST=192.168.1.10:8089 -e UCM_USER=api_user -e UCM_PASSWORD=... -- npx -y @ucm-control-kit/mcp

Other clients use the same command and variables. docs/mcp.md has setup for each one:

Agent Skill. skills/grandstream-ucm teaches an agent the full audit → reconcile → monitor → diagnose → test workflow and the safety rules. It follows the open Agent Skills format:

# Claude Code
cp -r skills/grandstream-ucm ~/.claude/skills/

Tools that read AGENTS.md (Codex, Copilot, Cursor, Jules and others) pick up the same guidance from AGENTS.md.

Library.

import { UcmClient, reconcile, tallyCalls, fetchCdr } from '@ucm-control-kit/core';
const ucm = new UcmClient({ host, user, password, allowWrites: ['dialExtension'] });
const offline = (await ucm.extensions()).filter((e) => !e.registered);

Voice

UCM_ALLOW_WRITES=dialExtension npx @ucm-control-kit/voice   # then open http://127.0.0.1:8765

• Push to talk. Hold the button or the Space bar and say "which phones are offline", "how many calls did each branch make today", or "test call from Harbour Road to Hill Street".

• No API key needed. Speech recognition and speech output run in the browser.

• Confirmation. Anything that rings a phone or changes a setting waits for a spoken "yes".

Using an LLM voice agent instead? Export the same tools for your platform:

import { exportTools } from '@ucm-control-kit/core';
exportTools('elevenlabs'); exportTools('openai'); exportTools('gemini'); exportTools('anthropic');

docs/voice.md has the full setup.

How it works

flowchart LR
  subgraph Surfaces
    CLI[ucm CLI]
    MCP[MCP server]
    VOICE[Voice console]
    APP[Your app]
  end
  TOOLS[tools.js<br/>one definition, confirmation rule]
  CORE[core<br/>client · audit · monitor · reconcile · diagnose · cdr · edit · testcall]
  UCM[(Grandstream UCM<br/>HTTPS /api)]
  CLI --> CORE
  MCP --> TOOLS
  VOICE --> TOOLS
  APP --> TOOLS
  TOOLS --> CORE
  CORE -- challenge/login · cookie · allow-listed writes --> UCM

Running many branches

These conventions make the automation reliable:

• Display names: the UCM display name should equal the branch name, so reconcile matches with full confidence.

• Numbering and addressing: give each region an extension range and each branch its own /24.

• Nightly checks: run audit, reconcile and a test call to each branch every night, and deal with the red items each morning.

• Known-good settings: keep a copy of each extension's last known-good settings, so recovery never starts from zero.

The full playbook covers onboarding wizard order, auto-heal levels and alert rules: skills/grandstream-ucm/references/multi-site.md.

Platform support

getSIPAccount, updateSIPAccount, dialExtension and cdrapi follow Grandstream's API guide. Run ucm probe to confirm them on your firmware. Please report your model so this table can grow. Details: docs/platforms.md.

The legacy HTTPS API Settings (Old) page is deprecated by Grandstream and isn't used here.

Security

• Writes: refused unless allow-listed (UCM_ALLOW_WRITES). UCM_DRY_RUN=1 previews them instead.

• Confirmation: agent and voice tools need confirm: true, and admin edits show a diff first. Ambiguous names are refused, never guessed.

• Out of scope: there is no delete or password-change tool, on purpose.

• Network: the voice console binds to 127.0.0.1 by default.

• Credentials: keep the UCM password in environment variables or a secret store, never in chat.

See SECURITY.md to report a vulnerability.

Contributing

Issues and PRs are welcome; see CONTRIBUTING.md. Run the tests with:

pnpm install && pnpm test

They run against a built-in fake UCM, so no hardware is needed.

License

MIT. Grandstream and UCM are trademarks of Grandstream Networks, Inc. This project is not affiliated with or endorsed by Grandstream.