3CX MCP Server

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.

1. Navigate to Integrations > API (German: Integrationen > API)

2. Click Add (Hinzufügen)

3. 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.

4. Check the XAPI access checkbox

5. Set Department to your main department (usually DEFAULT)

6. 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.

7. Click Save

8. A popup shows the API Secret — copy it immediately, it is only shown once!

9. 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

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

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

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

Testing

Test with MCP Inspector: npm run inspect (macOS/Linux) or npm run inspect:win (Windows). The .env file is loaded automatically.

Available Tools (22)

Troubleshooting

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.