3CX MCP Server
This server lets Claude connect to a 3CX phone system to manage users, monitor calls, search contacts, and administer telephony features.
User & extension management: create, update, delete, and list users/extensions; check registration, status, and presence.
Call monitoring: view active calls and call history (including missed calls, timezone-aware filters).
Contact search: find phonebook contacts by name, company, or phone number, including exact phone lookup.
Forwarding control: view and change an extension's forwarding profile (Available, Away, Out of office, etc.).
Queue & ring group management: find queues, list queue agents, and view ring groups.
Trunk administration: list SIP trunks and inspect trunk details/registration status.
Department administration: list, create, and update departments/groups.
System administration: get system health/license status and read event logs (errors, warnings, info).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@3CX MCP Server show me the active calls right now"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 likemcp-serverwill 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,RecordingsandScheduledReportsreturn 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 buildConfiguration
cp .env.example .envEdit .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_hereDeployment | Example FQDN | Port |
3CX Hosted |
| 443 |
Self-hosted (Linux/Windows) |
| 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:
npxArguments:
-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_hereTCX_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:8080npm run build && npm start
# Server listens on http://127.0.0.1:8080/mcp
# Health check: http://127.0.0.1:8080/healthSecurity: 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 aHostheader other than loopback, add it toMCP_ALLOWED_HOSTS(comma-separated). Never bind to0.0.0.0without 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) ornpm run inspect:win(Windows). The.envfile is loaded automatically.
Available Tools (22)
Tool | Type | Description |
| Read | System health, version, license, active calls count, disk usage |
| Read | System event logs (filter by Type: Error, Warning, Info) |
Tool | Type | Description |
| Read | Search users by name, extension, email, or mobile. Set |
| Read | Full details of one user by extension number (returns Id needed for update/delete; passwords/PIN are redacted) |
| Read | Quick status: is registered? current profile? queue status? |
| Write | Create a new extension |
| Write | Update user fields by Id |
| Write | Delete users by Id array |
Tool | Type | Description |
| Read | All forwarding profiles and routing rules for an extension |
| Write | Change active profile (Available, Away, Out of office, etc.) |
Tool | Type | Description |
| Read | All departments/groups |
| Write | Create a department |
| Write | Update department fields by Id |
Tool | Type | Description |
| Read | All SIP trunks with registration status |
| Read | Full trunk config by Id |
Tool | Type | Description |
| Read | Currently live calls |
| Read | Call history (V20 U6+ ReportCallLogData), newest-first, grouped into one row per call. Scope (today/last_24h/all), |
Tool | Type | Description |
| Read | Search queues by number or name |
| Read | Agents/members of a specific queue, with optional logged-in filter |
| Read | All ring groups |
Tool | Type | Description |
| Read | Search phonebook by name, company, or phone number |
| Read | Exact phone number lookup with normalization |
Troubleshooting
Error | Cause | Fix |
401 Unauthorized | Invalid credentials | Re-check |
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. |
Connection refused | Wrong port | Set |
fetch failed / ENOTFOUND | Wrong hostname | Verify |
Not sure if API works | Test credentials | Run: |
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 toolscreate_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
Scored across 22 tools
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.
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.
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.
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
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Hosted CallRail MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Lets Claude, Cursor or any MCP client build voice agents and place real phone calls.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that lets you schedule AI phone calls and manage Leximo assignments directly from Claude Desktop or Claude Code.1345 npm2MIT
- FlicenseNot gradedqualityCmaintenanceMCP server that integrates with Microsoft Dynamics 365 Business Central, enabling querying of customers, items, and sales orders through natural language commands in Claude Desktop.10-
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server with file management, HTTP requests, system info, and environment variable tools, plus a management UI and dual transport for Claude Desktop and Claude.ai.547 npmMIT
- AlicenseAqualityDmaintenanceMCP server that lets Claude place outbound telephone calls via ElevenLabs Agents over a SIP trunk and report the outcome including status, success evaluation, summary, and transcript.7ISC