Skip to content
MCP server

3CX MCP

Fleet health for 3CX phone systems: trunks, licences, versions and backups

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, macOS, Windows
Runs
Locally
Version
0.1.5
Listing updated
2 days ago

About 3CX MCP

3CX MCP is an open-source MCP server for communication. It runs locally on your machine and is started by your AI client.

Built for providers who run many customers' 3CX systems, this connector surfaces health across the whole fleet and exposes the full Configuration API on any single PBX. Example commands in the README include listing offline SIP trunks, licences or maintenance expiring within 60 days, and PBXes behind the newest build.

It is unofficial and unaffiliated with 3CX Ltd. Authentication uses a client ID, client secret and the PBX host name. For ChatGPT or Microsoft 365 Copilot Studio you host it over HTTPS with a bearer token set; Gemini CLI and Claude Code use the local binary.

Install

Run in a terminal

claude mcp add threecx-mcp --env THREECX_CLIENT_ID='<THREECX_CLIENT_ID>' --env THREECX_CLIENT_SECRET='<THREECX_CLIENT_SECRET>' --env THREECX_FQDN='<THREECX_FQDN>' --env THREECX_MCP_HTTP_TOKEN='<THREECX_MCP_HTTP_TOKEN>' -- npx -y https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb

Add to claude_desktop_config.json

{
  "mcpServers": {
    "threecx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb"
      ],
      "env": {
        "THREECX_CLIENT_ID": "<THREECX_CLIENT_ID>",
        "THREECX_CLIENT_SECRET": "<THREECX_CLIENT_SECRET>",
        "THREECX_FQDN": "<THREECX_FQDN>",
        "THREECX_MCP_HTTP_TOKEN": "<THREECX_MCP_HTTP_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "threecx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb"
      ],
      "env": {
        "THREECX_CLIENT_ID": "<THREECX_CLIENT_ID>",
        "THREECX_CLIENT_SECRET": "<THREECX_CLIENT_SECRET>",
        "THREECX_FQDN": "<THREECX_FQDN>",
        "THREECX_MCP_HTTP_TOKEN": "<THREECX_MCP_HTTP_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "threecx-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb"
      ],
      "env": {
        "THREECX_CLIENT_ID": "<THREECX_CLIENT_ID>",
        "THREECX_CLIENT_SECRET": "<THREECX_CLIENT_SECRET>",
        "THREECX_FQDN": "<THREECX_FQDN>",
        "THREECX_MCP_HTTP_TOKEN": "<THREECX_MCP_HTTP_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "threecx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb"
      ],
      "env": {
        "THREECX_CLIENT_ID": "<THREECX_CLIENT_ID>",
        "THREECX_CLIENT_SECRET": "<THREECX_CLIENT_SECRET>",
        "THREECX_FQDN": "<THREECX_FQDN>",
        "THREECX_MCP_HTTP_TOKEN": "<THREECX_MCP_HTTP_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "threecx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb"
      ],
      "env": {
        "THREECX_CLIENT_ID": "<THREECX_CLIENT_ID>",
        "THREECX_CLIENT_SECRET": "<THREECX_CLIENT_SECRET>",
        "THREECX_FQDN": "<THREECX_FQDN>",
        "THREECX_MCP_HTTP_TOKEN": "<THREECX_MCP_HTTP_TOKEN>"
      }
    }
  }
}

Configuration

  • THREECX_CLIENT_IDSet the THREECX_CLIENT_ID credential for the 3CX MCP server.Required
  • THREECX_CLIENT_SECRETSet the THREECX_CLIENT_SECRET credential for the 3CX MCP server.Required
  • THREECX_FQDNHost name of the 3CX phone system (for example pbx.example.com), the {fqdn} in https://{fqdn}/xapi/v1.Required
  • THREECX_BASE_URLOptional. Full XAPI base URL. Leave blank: the CLI builds https://<THREECX_FQDN>/xapi/v1. Set it only to point at a different host or port.
  • THREECX_TOKEN_URLOptional. Token endpoint the client-credentials exchange posts to. Leave blank: the CLI uses the phone system's own /connect/token. It must be on the same host as the API.
  • THREECX_OAUTH_SCOPEOptional. Scope sent with the client-credentials exchange. Leave blank to send none.
  • THREECX_FLEET_DIROptional. Absolute path of the directory holding the registry of client phone systems used by the fleet commands. Leave blank to use the CLI's config directory.
  • THREECX_PBXOptional. Name of one phone system registered with fleet add; the server then uses that PBX's host, client ID and secret variable (the same as --pbx). Leave blank to use THREECX_FQDN and the credentials above.
  • THREECX_MCP_READ_ONLYOptional. Set to exactly 1 to expose only read-only tools and refuse any state-changing execute call.
  • THREECX_NO_LOCAL_DATAOptional. Set to 1 to keep no local copy of API responses: reads go to the API and the response cache is off.
  • THREECX_MCP_HTTP_TOKENRequired only when running the MCP server with --transport http (a remote/hosted deployment). Callers must send a matching Authorization: Bearer header. Not needed for the default local stdio transport that Claude Desktop uses.
  • THREECX_USER_AGENTOptional. Overrides the User-Agent the CLI sends on 3CX requests. Leave blank to use the CLI's own built-in User-Agent.

What it does

Fleet health overview
Shows which client systems are failing or warning.
Trunk checks
Finds SIP trunks that are offline or misconfigured.
Licence expiry
Lists licences and maintenance due within a window.
Version gaps
Identifies PBXes behind the latest build.
Config API access
Full Configuration API for a single PBX.

Good for

  • Review all clients' phone systems each morning
  • Plan licence renewals 60 days ahead
  • Find PBXes needing updates
  • Diagnose a customer's trunk outage

Pricing

Open source

Free and open source; runs locally

3CX MCP FAQ

How do I connect it to ChatGPT?

Run it with the HTTP transport, an HTTPS host and a token, then add it as a Developer Mode connector.

Is it from 3CX?

No, it is community-built.

What credentials are needed?

THREECX_CLIENT_ID, THREECX_CLIENT_SECRET and THREECX_FQDN.

Is 3CX MCP free?

Yes. 3CX MCP is open source, so you can use and self-host it for free.

How do I add 3CX MCP to Claude Code?

Run this command in your terminal: claude mcp add threecx-mcp --env THREECX_CLIENT_ID='<THREECX_CLIENT_ID>' --env THREECX_CLIENT_SECRET='<THREECX_CLIENT_SECRET>' --env THREECX_FQDN='<THREECX_FQDN>' --env THREECX_MCP_HTTP_TOKEN='<THREECX_MCP_HTTP_TOKEN>' -- npx -y https://github.com/Servosity/msp-skills/releases/download/threecx-v0.1.5/threecx-mcp.mcpb

What are the best alternatives to 3CX MCP?

The closest alternatives to 3CX MCP are BoardAgent, Callout, nicemails, SOMMON Office and PostBaton.

Alternatives to 3CX MCP

  1. BoardAgent

    MCP server

    Remote MCP server for a message board where only AI agents post, reply and vote

    • 27 tools
    • Remote
    • Free
    • Community directories
  2. Callout

    MCP server

    Let an AI agent place real phone calls in Japanese or English and read the transcript

    • 5 tools
    • Remote
    • Freemium
    • Communication
  3. nicemails

    MCP server

    Give each AI agent its own real mailbox to read, search and send email with your approval

    • 8 tools
    • Remote
    • Freemium
    • Communication
  4. SOMMON Office

    MCP server

    Send real paper letters via Deutsche Post from an AI assistant, to 218 countries

    Not checked yet
    • 14 tools
    • Remote
    • Paid
    • Communication
  5. PostBaton

    MCP server

    Schedule, edit and cancel social posts across networks from an AI assistant or REST API

    Not checked yet
    • Remote
    • Freemium
    • Marketing and SEO
  6. MeetBetr

    MCP server

    Find when friends are free and send them a plan after you confirm it

    • Remote
    • Free
    • Productivity