GitHub - SSIG-IT/3cx-mcp-server: MCP Server for 3CX Phone System (V20+) — Manage users, extensions, queues, calls, contacts and more via Claude Desktop, Claude Code or any MCP client. 21 tools including CRUD operations.

An MCP (Model Context Protocol) server that connects Claude to a 3CX Phone System (V20+). Manage users, monitor calls, search contacts, configure forwarding — directly from Claude Desktop, Claude Code, or any MCP-compatible client.

Features

User Management — list, create, update, delete users and extensions
Call Monitoring — view active calls and call history (CDR)
Contact Search — search and browse the 3CX phonebook
Queue & Ring Group Status — monitor call queues and ring groups
Forwarding Control — view and change forwarding profiles per extension
System Administration — system status, trunks, departments, event logs

The server authenticates via OAuth2 Client Credentials against the 3CX Configuration API (XAPI), manages token lifecycle automatically, and exposes 22 tools over MCP's stdio transport.

Quick Start

git clone https://github.com/SSIG-IT/3cx-mcp-server.git && cd 3cx-mcp-server
npm install && npm run build
cp .env.example .env  # edit with your 3CX credentials
npm start

Contents: Prerequisites · API Setup · Installation · Configuration · Usage · Tools (22) · Troubleshooting · Deutsch

Prerequisites

Node.js 20 or later
3CX V20+ (hosted or self-hosted)
3CX License with XAPI access — Enterprise (ENT/AI) or Enterprise Plus (ENT+)

3CX API Setup

Log in to your 3CX Web Client as System Owner. Click the gear icon (bottom left) to enter the Admin area.

Navigate to Integrations > API (German: Integrationen > API)
Click Add (Hinzufügen)
Enter a Client ID — must be a numeric extension number (e.g. 900, 950). Text values like mcp-server will be rejected. Choose an unused number.
Check the XAPI access checkbox
Set Department to your main department (usually DEFAULT)
Set the Role to System Owner (Systemeigentümer)

⚠️ The role MUST be "System Owner", NOT "System Administrator". With System Administrator, most tools work but get_call_history, ChatHistoryView, Recordings and ScheduledReports return 403.

Click Save
A popup shows the API Secret — copy it immediately, it is only shown once!
Store Client ID and API Secret securely (e.g. in a password manager)

Installation

git clone https://github.com/SSIG-IT/3cx-mcp-server.git
cd 3cx-mcp-server
npm install
npm run build

Configuration

cp .env.example .env

Edit .env with your values:

TCX_FQDN=your-company.my3cx.de
TCX_PORT=443
TCX_TIMEZONE=Europe/Berlin
TCX_CLIENT_ID=900
TCX_CLIENT_SECRET=your_api_secret_here

Deployment	Example FQDN	Port
3CX Hosted	`company.my3cx.de`, `company.3cx.eu`	443
Self-hosted (Linux/Windows)	`pbx.company.com`	5001

If unsure, try port 443 first. If you get "Connection refused", switch to 5001.

For call-history queries like "missed calls today", set TCX_TIMEZONE to your business/PBX timezone. Otherwise, today falls back to the MCP host timezone, which may be UTC on remote hosts.

Usage

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "3cx": {
      "command": "node",
      "args": ["/absolute/path/to/3cx-mcp-server/build/index.js"],
      "env": {
        "TCX_FQDN": "your-company.my3cx.de",
        "TCX_PORT": "443",
        "TCX_CLIENT_ID": "900",
        "TCX_CLIENT_SECRET": "your_api_secret_here"
      }
    }
  }
}

For Claude Code in VS Code, use the same configuration in your VS Code settings.json under claude.mcpServers.

MetaMCP

For MetaMCP, add the server with:

Command: npx
Arguments: -y github:SSIG-IT/3cx-mcp-server

Set these environment variables:

TCX_FQDN=your-company.my3cx.de
TCX_PORT=443
TCX_TIMEZONE=Europe/Berlin
TCX_CLIENT_ID=900
TCX_CLIENT_SECRET=your_api_secret_here

TCX_TIMEZONE is strongly recommended — it defines the day boundary for get_call_history(scope="today"). Without it, "today" falls back to the host timezone (may be UTC on remote systems).

To force a fresh install after updates: npx --force -y github:SSIG-IT/3cx-mcp-server

Standalone HTTP Transport

Run the server as a remote HTTP endpoint (without MetaMCP):

MCP_TRANSPORT=http
MCP_HTTP_PORT=8080
MCP_HTTP_HOST=127.0.0.1
# MCP_ALLOWED_HOSTS=mcphub.internal:8080

npm run build && npm start
# Server listens on http://127.0.0.1:8080/mcp
# Health check: http://127.0.0.1:8080/health

Security: the HTTP transport has no built-in authentication and binds to loopback (127.0.0.1) by default. It is meant to run behind an authenticating proxy (e.g. mcphub OAuth). DNS-rebinding protection is enabled; if your proxy forwards a Host header other than loopback, add it to MCP_ALLOWED_HOSTS (comma-separated). Never bind to 0.0.0.0 without an auth proxy — the server holds 3CX admin credentials and exposes write tools.

Deploy behind a reverse proxy (nginx/Cloudflare) with HTTPS for production use.

Testing

Unit tests: npm test (Vitest — OData escaping, timezone/day-range math, call grouping, response formatting).
MCP Inspector: npm run inspect (macOS/Linux) or npm run inspect:win (Windows). The .env file is loaded automatically.

Available Tools (22)

System — 2 tools

Tool	Type	Description
`get_system_status`	Read	System health, version, license, active calls count, disk usage
`get_event_logs`	Read	System event logs (filter by Type: Error, Warning, Info)

Users & Extensions — 6 tools

Tool	Type	Description
`find_users`	Read	Search users by name, extension, email, or mobile. Set `onlyRegistered=true` for online users
`get_user`	Read	Full details of one user by extension number (returns Id needed for update/delete; passwords/PIN are redacted)
`get_extension_status`	Read	Quick status: is registered? current profile? queue status?
`create_user`	Write	Create a new extension
`update_user`	Write	Update user fields by Id
`delete_user`	Write	Delete users by Id array

Forwarding — 2 tools

Tool	Type	Description
`get_forwarding_profiles`	Read	All forwarding profiles and routing rules for an extension
`set_forwarding_profile`	Write	Change active profile (Available, Away, Out of office, etc.)

Departments — 3 tools

Tool	Type	Description
`list_departments`	Read	All departments/groups
`create_department`	Write	Create a department
`update_department`	Write	Update department fields by Id

Trunks — 2 tools

Tool	Type	Description
`list_trunks`	Read	All SIP trunks with registration status
`get_trunk_details`	Read	Full trunk config by Id

Calls & History — 2 tools

Tool	Type	Description
`get_active_calls`	Read	Currently live calls
`get_call_history`	Read	Call history (V20 U6+ ReportCallLogData), newest-first, grouped into one row per call. Scope (today/last_24h/all), `missedOnly` (no segment answered), extension/queue filter. Timezone-correct (UTC-mapped). 3CX caps reports at 20 000 rows — narrow the window for busy periods.

Queues — 3 tools

Tool	Type	Description
`find_queues`	Read	Search queues by number or name
`get_queue_agents`	Read	Agents/members of a specific queue, with optional logged-in filter
`list_ring_groups`	Read	All ring groups

Contacts — 2 tools

Tool	Type	Description
`search_contacts`	Read	Search phonebook by name, company, or phone number
`find_contact_by_phone`	Read	Exact phone number lookup with normalization

Troubleshooting

Error	Cause	Fix
401 Unauthorized	Invalid credentials	Re-check `TCX_CLIENT_ID` and `TCX_CLIENT_SECRET`. Regenerate the API key if the secret was lost.
403 Forbidden on get_call_history	Wrong role	Service principal role must be System Owner, not System Administrator.
"Format invalid" creating API key	Non-numeric Client ID	The Client ID must be a number (e.g. `900`), not text.
Connection refused	Wrong port	Set `TCX_PORT=443` for hosted `*.my3cx.de` instances, `5001` for self-hosted.
fetch failed / ENOTFOUND	Wrong hostname	Verify `TCX_FQDN` is correct and reachable via HTTPS.
Not sure if API works	Test credentials	Run: `curl -s -X POST "https://FQDN/connect/token" -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=ID&client_secret=SECRET&grant_type=client_credentials"` — should return JSON with `access_token`.

License

MIT — see LICENSE

Contributing

See CONTRIBUTING.md

Deutsch

Einrichtung: [3CX Admin] Integrationen > API > Hinzufügen > Client-ID (numerisch, z.B. 900) > XAPI aktivieren > Rolle: Systemeigentümer > Speichern > API-Key sofort kopieren. Port 443 für gehostete Instanzen (*.my3cx.de), Port 5001 für selbst-gehostete. Vollständige Anleitung: siehe englische Dokumentation oben.

Made with MCP by SSIG-IT GmbH · Blaubeuren, Germany

Name		Name	Last commit message	Last commit date
assets		assets
docs		docs
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
server.json		server.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

Features

Prerequisites

3CX API Setup

Installation

Configuration

Usage

MetaMCP

Standalone HTTP Transport

Testing

Available Tools (22)

Troubleshooting

License

Contributing

Deutsch

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Features

Prerequisites

3CX API Setup

Installation

Configuration

Usage

MetaMCP

Standalone HTTP Transport

Testing

Available Tools (22)

Troubleshooting

License

Contributing

Deutsch

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages