VoIPSense Maroc MCP Server

A Model Context Protocol server for the VoIPSense Cloud public API. It lets Claude (and any MCP client) place and control calls, read call results, fetch recordings and push leads into your call center, all in plain language. An optional console mode adds dashboards, live switchboard status, PBX configuration, the built-in CRM and the omnichannel inbox.

"Call 0612345678 from extension 11151, then send me yesterday's answered calls for the Prospection Web campaign."

🇫🇷 Version française plus bas

Features

Console mode tools (optional, VOIPSENSE_EMAIL + VOIPSENSE_PASSWORD)

These use the same API as the VoIPSense web console, authenticated as a console user. See Console mode before enabling it.

Write tools carry MCP annotations (destructiveHint, idempotentHint…) so clients like Claude ask for confirmation appropriately. A read-only mode removes every write tool (see Configuration).

Related MCP server: GoHighLevel MCP Server

1. Get an API key

In the VoIPSense console: Intégrations → API Keys → Nouvelle clé. Tick only the permissions you need (table above). The key (vsk_…) is shown once, so store it safely.

Rate limit: 100 requests / minute per key (HTTP 429 beyond that).

Requirements: Node.js 18+ (node -v). Nothing else to install: npx downloads the server on first run.

2. Add it to Claude

Claude Desktop

1. Open Settings → Developer → Edit Config. This opens claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server:

{
  "mcpServers": {
    "voipsense": {
      "command": "npx",
      "args": ["-y", "voipsense-maroc-mcp"],
      "env": {
        "VOIPSENSE_API_KEY": "vsk_your_key_here"
      }
    }
  }
}

3. Quit Claude Desktop completely and reopen it. The VoIPSense tools appear under the 🔨 / connectors menu.

Use cmd as the command:

"voipsense": {
  "command": "cmd",
  "args": ["/c", "npx", "-y", "voipsense-maroc-mcp"],
  "env": { "VOIPSENSE_API_KEY": "vsk_your_key_here" }
}

Claude Code (CLI)

claude mcp add voipsense --scope user -e VOIPSENSE_API_KEY=vsk_your_key_here -- npx -y voipsense-maroc-mcp

Check it with claude mcp list, or /mcp inside a session. To share it with a team through the repo, use --scope project: this writes a .mcp.json file. Keep the key out of git by referencing an environment variable:

{
  "mcpServers": {
    "voipsense": {
      "command": "npx",
      "args": ["-y", "voipsense-maroc-mcp"],
      "env": { "VOIPSENSE_API_KEY": "${VOIPSENSE_API_KEY}" }
    }
  }
}

Claude.ai (web) and mobile

Claude.ai custom connectors need a remote (HTTP) MCP server. This package runs locally over stdio, so use Claude Desktop or Claude Code.

Other MCP clients

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "voipsense": {
      "command": "npx",
      "args": ["-y", "voipsense-maroc-mcp"],
      "env": { "VOIPSENSE_API_KEY": "vsk_your_key_here" }
    }
  }
}

.vscode/mcp.json. The key is prompted once and stored securely:

{
  "inputs": [
    { "type": "promptString", "id": "voipsense-key", "description": "VoIPSense API key", "password": true }
  ],
  "servers": {
    "voipsense": {
      "command": "npx",
      "args": ["-y", "voipsense-maroc-mcp"],
      "env": { "VOIPSENSE_API_KEY": "${input:voipsense-key}" }
    }
  }
}

Any client that supports stdio MCP servers works. Command: npx, args: ["-y", "voipsense-maroc-mcp"], env: VOIPSENSE_API_KEY.

Configuration

* Set the API key, the console credentials, or both. Each set enables its own group of tools.

Tip: for reporting-only use, create a key with just cdr:read / recordings:read / callcenter:read and set VOIPSENSE_READ_ONLY=true.

Console mode (optional)

Console mode signs in to the VoIPSense web console with an email and password, exactly like the browser does (POST /api/auth/login → 24h access token, renewed automatically with the 30-day refresh cookie). It unlocks the console tools listed above.

"env": {
  "VOIPSENSE_API_KEY": "vsk_your_key_here",
  "VOIPSENSE_EMAIL": "mcp-bot@your-company.ma",
  "VOIPSENSE_PASSWORD": "a-strong-password"
}

Before enabling it:

• Create a dedicated user for the MCP server (Paramètres → Utilisateurs) with the lowest role that covers your needs (SUPERVISOR for reporting, ADMIN only if required). Don't use your personal admin account: everything the tools do is done as that user.

• Two-factor authentication is not supported: the dedicated user must not have 2FA enabled.

• The password sits in your MCP config file in plain text, like the API key. Keep that file private, and prefer ${VOIPSENSE_PASSWORD} environment references in shared .mcp.json files.

• This API is not the documented public API. Routes were mapped from the web console and may change without notice. If a console tool breaks, the public API tools keep working.

• Use VOIPSENSE_READ_ONLY=true to keep console mode to reads only.

Example prompts

• "Call 0612345678 and connect it to extension 11151 with caller ID 0520123456."

• "Transfer call api-lq2x9-12345 to queue 8001." / "Hang up that call."

• "Show me all outbound answered calls since June 1st, grouped by disposition."

• "Find the recordings for 0612345678 this month and download the latest one."

• "Create the list 'Leads Site Web : Août' on a new 'Prospection Web' campaign, assign all agents, and inject these 1,200 leads from leads.csv."

• "Which outbound line does each campaign use?"

• "Tag contact 0600000000 in the Clinique Atlas sub-account with the services Implant and Blanchiment."

• (console) "Who is available right now, and is anyone waiting in a queue?"

• (console) "Compare this week's answer rate per agent and per line, and list abandoned calls over 30 s."

• (console) "Block 0522000000 for outbound calls until the end of the month."

• (console) "Show open WhatsApp conversations and summarize the last messages of each."

Good to know (from the VoIPSense API guide)

• Leads are idempotent per phone number and list: resending the same file creates no duplicates (duplicates counter). Add updateIfExists: true to update existing contacts (their customFields are then fully replaced).

• A list without a campaign is invisible to agents, and a campaign without enrolled agents shows an empty console. inject_leads_batch with campaignName + createCampaign + assignAllAgents (or agents) handles both in one step.

• API-created campaigns are PREVIEW / ACTIVE: agents receive leads as soon as they're "ready". MANUAL serves no leads.

• Outbound line priority: list line (outboundLine, set at list creation) → campaign line → first active / first free line.

• Unknown agents in agents → 400 and nothing is written; partially valid → agentsNotFound + warning in the response.

• Real-time webhooks (call.started, call.ended, disposition.submitted…) and CRM sync are configured in the console, not through this server.

Error codes

Development

git clone https://github.com/Yasmine-Works/VoIPSense-Maroc-MCP.git
cd VoIPSense-Maroc-MCP
npm install
npm run build
VOIPSENSE_API_KEY=vsk_... npm run inspect   # opens the MCP Inspector

Run your local build from Claude Code:

claude mcp add voipsense-dev -e VOIPSENSE_API_KEY=vsk_... -- node /absolute/path/to/VoIPSense-Maroc-MCP/dist/index.js

Releasing

1. Bump the version: npm version patch (or minor / major).

2. git push --follow-tags.

3. Create a GitHub Release for the tag. The Publish workflow publishes to npm with provenance. It needs an NPM_TOKEN repository secret (npm granular access token with publish rights on voipsense-maroc-mcp).

🇫🇷 Démarrage rapide (français)

Serveur MCP pour l'API publique VoIPSense Cloud : lancer / transférer / raccrocher des appels, lire les résultats et dispositions, télécharger les enregistrements, injecter des leads (liste + campagne + agents en un seul appel) et gérer les services GoHighLevel, directement depuis Claude.

1. Clé API : Console VoIPSense → Intégrations → API Keys → Nouvelle clé. Cochez les permissions utiles (pbx:write, cdr:read, recordings:read, callcenter:read, callcenter:write). La clé n'est affichée qu'une seule fois.

2. Claude Desktop : Réglages → Développeur → Modifier la config, puis ajoutez :

   {
     "mcpServers": {
       "voipsense": {
         "command": "npx",
         "args": ["-y", "voipsense-maroc-mcp"],
         "env": { "VOIPSENSE_API_KEY": "vsk_votre_cle_ici" }
       }
     }
   }

   Redémarrez Claude Desktop.

3. Claude Code :

   claude mcp add voipsense --scope user -e VOIPSENSE_API_KEY=vsk_votre_cle_ici -- npx -y voipsense-maroc-mcp

4. Demandez par exemple : « Appelle le 0612345678 depuis le poste 11151 », « Liste les appels répondus de la campagne Prospection Web depuis le 1er juin », « Injecte ces leads dans la liste "Leads Site Web : Août" sur la campagne "Prospection Web" et inscris tous les agents ».

Mode console (optionnel) : ajoutez VOIPSENSE_EMAIL et VOIPSENSE_PASSWORD d'un utilisateur dédié sans 2FA pour débloquer statistiques, état en direct des postes et files, configuration PBX, CRM et boîte de réception omnicanale. Cette API est celle de la console web (non documentée) : elle peut évoluer sans préavis.

Mode lecture seule : ajoutez "VOIPSENSE_READ_ONLY": "true" dans env. Support VoIPSense : contact@voipsensemaroc.com

License

MIT. This is a community integration and is not an official VoIPSense product.