Skip to main content
Glama
3CX MCP Server

3CX MCP Server

by SSIG-IT

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

Related MCP server: Business Central MCP Workshop Server

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.

  1. Click Save

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

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

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)

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

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

Tool

Type

Description

list_departments

Read

All departments/groups

create_department

Write

Create a department

update_department

Write

Update department fields by Id

Tool

Type

Description

list_trunks

Read

All SIP trunks with registration status

get_trunk_details

Read

Full trunk config by Id

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.

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

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.


Available Tools

22 tools
create_departmentB

[DESTRUCTIVE] Creates a new department (group) in 3CX. Returns the created department with its assigned Id.

Inputs: Name (required), Language, TimeZoneId.

create_userA

[DESTRUCTIVE] Creates a new 3CX user/extension. The Number must be unused — use find_users first to check availability. Returns the created user with its assigned Id. Requires confirmation from the user before executing.

Inputs: Number (required), FirstName (required), LastName (required), EmailAddress (required), +1 more.

delete_userA

[DESTRUCTIVE] Permanently deletes 3CX users by their numeric Ids. Cannot be undone. Get Ids from get_user or list_users first. Accepts an array to delete multiple users at once.

Inputs: ids (required).

find_contact_by_phoneA

Use this when the user provides a specific phone number and wants to know who it belongs to: 'whose number is +49 731 123456?', 'who called from 0176-1234567?'. Normalizes the number (ignores spaces, dashes, formatting) for exact matching across all phone fields.

Inputs: phone (required), top, scanLimit.

find_queuesA

Use this when the user asks about call queues: 'show all queues', 'find support queue', 'which queue is 802?'. Searches by queue number or name with fuzzy matching. Returns: Id, Number, Name, IsRegistered, PollingStrategy, Agents (with login status), RingTimeout, MaxWaitTime. Use get_queue_agents for detailed agent info on a specific queue.

Inputs: query (required), top.

find_usersA

Use this when the user asks about people, extensions, or phone users. Searches across extension number, first name, last name, display name, email, and mobile. Examples: 'find Philipp', 'who has extension 101?', 'who is online?', 'list all users'. Set onlyRegistered=true for 'who is online/registered?' questions. Returns: Id, Number, FirstName, LastName, DisplayName, EmailAddress, Mobile, IsRegistered, CurrentProfileName, QueueStatus, Enabled.

Inputs: query (required), top, includeDisabled, onlyRegistered, +1 more.

get_active_callsA

Returns all currently active (live) calls on the 3CX system. Each call includes caller/callee info, duration, and status. Returns an empty array if no calls are in progress. Use this for 'who is on the phone right now?' questions.

Inputs: no named parameters.

get_call_historyA

Use this for ANY question about past calls: 'show today's calls', 'missed calls today', 'recent calls for extension 101', 'calls to queue 802 yesterday'. Returns newest calls first. Each record: StartTime, SourceDisplayName, SourceCallerId, DestinationDisplayName, DestinationCallerId, Answered (true/false), TalkingDuration, Direction, Status, Reason. Set missedOnly=true for missed/unanswered calls. Handles timezone-aware 'today' filtering automatically. Requires System Owner role.

Inputs: scope, missedOnly, date, timezone, +4 more.

get_event_logsA

Returns system event logs from 3CX. Each entry has: Id, Type (Info/Warning/Error), EventId, Message. Filter examples: "Type eq 'Error'" for errors only, "Type eq 'Warning'" for warnings. Use this for 'are there any errors on the phone system?' or 'show me recent system events' questions.

Inputs: filter, top, skip.

get_extension_statusA

Use this when the user asks 'is extension 101 online?', 'what status has extension 200?', or 'is Philipp available?'. Returns: Number, DisplayName, IsRegistered (true=phone connected), CurrentProfileName (Available/Away/Out of office), QueueStatus (LoggedIn/LoggedOut). For full user details use get_user, for searching by name use find_users.

Inputs: extension (required).

get_forwarding_profilesA

Use this when the user asks 'how are calls routed for extension 101?', 'what forwarding profiles does 200 have?', or 'show me the call routing for Philipp'. Returns the active profile name and all available profiles (Available, Away, Out of office, Custom 1, Custom 2) with their routing rules. Call this before set_forwarding_profile to see valid profile names.

Inputs: extension (required).

get_queue_agentsA

Use this when the user asks 'who is in queue X?', 'which agents are logged into 802?', or 'who is working the support queue?'. Resolves the queue by number or name, then returns its agents with login status. Set loggedInOnly=true to show only currently logged-in agents.

Inputs: queue (required), loggedInOnly.

get_system_statusA

Returns 3CX system overview. Fields: FQDN, Version, Activated, MaxSimCalls, ExtensionsRegistered, ExtensionsTotal, TrunksRegistered, TrunksTotal, CallsActive, LicenseActive, ExpirationDate, MaintenanceExpiresAt, Support, ProductCode, BackupScheduled, LastBackupDateTime, DiskUsage, FreeDiskSpace, OS. Use this to check system health, license status, or how many active calls are running.

Inputs: no named parameters.

get_trunk_detailsA

Returns full configuration of a specific SIP trunk including registration details, codecs, routes, and authentication. Get the trunk Id from list_trunks first.

Inputs: id (required).

get_userA

Use this when the user asks about ONE specific extension by number. Returns the complete user record including the numeric Id (needed for update_user and delete_user). Fields: Id, Number, FirstName, LastName, DisplayName, EmailAddress, Mobile, IsRegistered, CurrentProfileName, QueueStatus, Enabled, Tags. Always call this before update_user or delete_user to get the Id.

Inputs: extension (required).

list_departmentsA

Returns all 3CX departments (called 'Groups' in the API). Each department has: Id, Name, Number, Language, TimeZoneId, Members. The Id is needed for update_department. Filter examples: "Name eq 'Sales'", "Name eq 'DEFAULT'".

Inputs: filter.

list_ring_groupsA

Use this when the user asks about ring groups (not queues). Ring groups ring multiple extensions simultaneously or in sequence. Returns: Id, Number, Name, Members, RingStrategy.

Inputs: filter.

list_trunksA

Returns all SIP trunks configured on the 3CX system. Each trunk has: Id, Number, Name, IsOnline (registration status), Direction, SimultaneousCalls. Use get_trunk_details with the Id for full configuration details.

Inputs: no named parameters.

search_contactsA

Use this when the user asks about contacts or the phonebook: 'find contact Mueller', 'search for Acme', 'who has number 0731...'. Searches across FirstName, LastName, CompanyName, Business phone, and PhoneNumber. Returns: Id, FirstName, LastName, CompanyName, PhoneNumber, Business, Email, Department, Title. For exact phone number matching (ignoring formatting), use find_contact_by_phone instead.

Inputs: query (required).

set_forwarding_profileA

[DESTRUCTIVE] Use this when the user wants to change call routing: 'set extension 101 to Away', 'put Philipp on DND'. Changes take effect immediately. Valid profiles: 'Available', 'Away', 'Out of office', 'Custom 1', 'Custom 2'. Call get_forwarding_profiles first if you need to verify available profile names. Requires user confirmation.

Inputs: extension (required), profile (required).

update_departmentA

[DESTRUCTIVE] Updates a 3CX department by its numeric Id. Get the Id from list_departments first. Only provided fields are changed.

Inputs: id (required), Name, Language, TimeZoneId.

update_userA

[DESTRUCTIVE] Updates a 3CX user by numeric Id. Get the Id from get_user or list_users first. Only provided fields are changed. Can update name, email, mobile, or enable/disable a user.

Inputs: id (required), FirstName, LastName, EmailAddress, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 22 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action (e.g., find_users for searching, get_user for a specific user, get_extension_status for online status). Tools with similar domains are differentiated by scope or purpose.

    Naming Consistency5/5

    Nearly all tools follow a clear verb_noun pattern (create_user, list_departments, get_active_calls). The one exception, find_contact_by_phone, is still understandable and does not break the overall consistency.

    Tool Count5/5

    With 22 tools, the server covers the essential operations of a phone system without being bloated. Each tool serves a specific purpose, and the count feels well-scoped.

    Completeness3/5

    Core operations exist for users and departments (CRUD), but other important areas like contacts, queues, and trunks lack create/update/delete capabilities, making the tool set incomplete for full administrative workflows.

    Related MCP Connectors

    Related MCP Servers