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.

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

🇫🇷 Version française plus bas

Features

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

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

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

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