ictpbx-mcp — Claude Code MCP server: read PBX state, change nothing
Bridges your ICTPBX phone system into an AI assistant. Extensions, inbound numbers, carriers, tenants and live counters come back as plain answers.
claude mcp add --env ICTPBX_BASE_URL=<ICTPBX_BASE_URL> --env ICTPBX_USERNAME=<ICTPBX_USERNAME> --env ICTPBX_PASSWORD=<ICTPBX_PASSWORD> --env ICTPBX_TIMEOUT_MS=<ICTPBX_TIMEOUT_MS> --env ICTPBX_TLS_INSECURE=<ICTPBX_TLS_INSECURE> --transport stdio ictpbx-mcp -- npx -y ictpbx-mcpWhat ictpbx-mcp does
The server talks to the ICTCore REST API underneath ICTPBX. On the first request it authenticates over email and password, takes the JWT from POST /authenticate, then keeps it fresh on its own. Five tools cover the usual questions: how many extensions, devices, ring groups, queues, IVRs, voicemails, conferences and gateways exist; which extensions are configured; which DID numbers are active; which upstream SIP carriers are set; which customer organizations live on the box.
Node.js 18 or newer is the baseline. You supply the REST base address (usually ending in /api), the account email and its password. Requests time out after 30000 ms unless you change ICTPBX_TIMEOUT_MS. There is also ICTPBX_TLS_INSECURE for skipping certificate checks — point it at a self-signed test install, never at a production PBX, because it switches off the check that the server is who it claims.
Everything is read-only by design. The tool set has no write path, so an agent cannot alter a trunk or dial out. Setup is a single npx launch with the credentials passed through the environment.
What it helps with
- count extensions and devices on the PBX
- list inbound DID numbers with active state
- see which SIP carriers the PBX uses
- pull the tenants registered on the system
- check queue and IVR totals in chat
Example prompts for the agent
- Give me the PBX statistics: extensions, ring groups and conferences.
- List every DID number with its tenant and whether it is active.
- Which SIP trunk providers are configured on our ICTPBX?
How to install ictpbx-mcp
Platform CLI
claude mcp add --env ICTPBX_BASE_URL=<ICTPBX_BASE_URL> --env ICTPBX_USERNAME=<ICTPBX_USERNAME> --env ICTPBX_PASSWORD=<ICTPBX_PASSWORD> --env ICTPBX_TIMEOUT_MS=<ICTPBX_TIMEOUT_MS> --env ICTPBX_TLS_INSECURE=<ICTPBX_TLS_INSECURE> --transport stdio ictpbx-mcp -- npx -y ictpbx-mcpReplace <…> with your own values
Platform CLI
codex mcp add ictpbx-mcp --env ICTPBX_BASE_URL=<ICTPBX_BASE_URL> --env ICTPBX_USERNAME=<ICTPBX_USERNAME> --env ICTPBX_PASSWORD=<ICTPBX_PASSWORD> --env ICTPBX_TIMEOUT_MS=<ICTPBX_TIMEOUT_MS> --env ICTPBX_TLS_INSECURE=<ICTPBX_TLS_INSECURE> -- npx -y ictpbx-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"ictpbx-mcp": {
"command": "npx",
"args": [
"-y",
"ictpbx-mcp"
],
"env": {
"ICTPBX_BASE_URL": "<ICTPBX_BASE_URL>",
"ICTPBX_USERNAME": "<ICTPBX_USERNAME>",
"ICTPBX_PASSWORD": "<ICTPBX_PASSWORD>",
"ICTPBX_TIMEOUT_MS": "<ICTPBX_TIMEOUT_MS>",
"ICTPBX_TLS_INSECURE": "<ICTPBX_TLS_INSECURE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"ictpbx-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ictpbx-mcp"
],
"env": {
"ICTPBX_BASE_URL": "<ICTPBX_BASE_URL>",
"ICTPBX_USERNAME": "<ICTPBX_USERNAME>",
"ICTPBX_PASSWORD": "<ICTPBX_PASSWORD>",
"ICTPBX_TIMEOUT_MS": "<ICTPBX_TIMEOUT_MS>",
"ICTPBX_TLS_INSECURE": "<ICTPBX_TLS_INSECURE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e ICTPBX_BASE_URL=<ICTPBX_BASE_URL> -e ICTPBX_USERNAME=<ICTPBX_USERNAME> -e ICTPBX_PASSWORD=<ICTPBX_PASSWORD> -e ICTPBX_TIMEOUT_MS=<ICTPBX_TIMEOUT_MS> -e ICTPBX_TLS_INSECURE=<ICTPBX_TLS_INSECURE> ictpbx-mcp npx -y ictpbx-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ictpbx-mcp
How do I install ictpbx-mcp in Claude Code?
Run `claude mcp add ictpbx-mcp -e ICTPBX_BASE_URL=<ICTPBX_BASE_URL> -e ICTPBX_USERNAME=<ICTPBX_USERNAME> -e ICTPBX_PASSWORD=<ICTPBX_PASSWORD> -- npx -y ictpbx-mcp with your REST base, account email and password in place of the placeholders. The extended form adds timeout and TLS settings: claude mcp add --env ICTPBX_BASE_URL=<ICTPBX_BASE_URL> --env ICTPBX_USERNAME=<ICTPBX_USERNAME> --env ICTPBX_PASSWORD=<ICTPBX_PASSWORD> --env ICTPBX_TIMEOUT_MS=<ICTPBX_TIMEOUT_MS> --env ICTPBX_TLS_INSECURE=<ICTPBX_TLS_INSECURE> --transport stdio ictpbx-mcp -- npx -y ictpbx-mcp`.
What does ictpbx-mcp do?
It reads the state of your ICTPBX over the ICTCore REST API and exposes five tools to the assistant: statistics, extensions, DID numbers, SIP trunk providers and tenants. It never places a call or edits configuration.
What do I need before connecting it?
Node.js 18 or newer, the ICTCore REST base address (normally with /api at the end), plus the API account email and password. Login is by email, and the JWT is fetched through POST /authenticate.
