Skip to content
Back to search

funnelchat-api-mcp

MCP server for the Funnelchat public API (@funnelchat-hq/mcp)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/funnelchat20--funnelchat-api-mcp/badge.svg)](/listings/funnelchat20--funnelchat-api-mcp)

HTML

<a href="/listings/funnelchat20--funnelchat-api-mcp"><img src="/api/listings/funnelchat20--funnelchat-api-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 194 lines
  1. # @funnelchat-hq/mcp
  2. El servidor MCP de la API pública de Funnelchat. Con él, tu asistente (Claude Code, Cursor u otro cliente MCP) usa tus números de WhatsApp, tus mensajes, contactos, plantillas, grupos y webhooks con tu clave de API: los mismos permisos, límites y errores que la API.
  3. Cubre todas las llamadas que publica el [portal de desarrolladores](https://developers-portal.funnelchat.app/docs/) con 20 tools, unos 3.100 tokens en total.
  4. ## Antes de empezar
  5. - Node 20.11 o más.
  6. - Una clave de API: en el panel, **Desarrolladores → Crear clave**. Dale solo los permisos que necesitas. La clave va en la configuración del servidor MCP, nunca en el chat.
  7. ## Instalarlo
  8. ### Claude Code
  9. ```bash
  10. claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp
  11. ```
  12. Para que solo pueda leer, agrega `--read-only` al final:
  13. ```bash
  14. claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp --read-only
  15. ```
  16. ### Cursor
  17. En `.cursor/mcp.json` (de tu proyecto) o en `~/.cursor/mcp.json`:
  18. ```json
  19. {
  20. "mcpServers": {
  21. "funnelchat": {
  22. "command": "npx",
  23. "args": ["-y", "@funnelchat-hq/mcp"],
  24. "env": { "FUNNELCHAT_API_KEY": "tu_clave" }
  25. }
  26. }
  27. }
  28. ```
  29. ### Otros clientes MCP
  30. Todos piden lo mismo: el comando `npx -y @funnelchat-hq/mcp` y la variable `FUNNELCHAT_API_KEY`.
  31. - **Claude Desktop**: el mismo bloque `mcpServers` de Cursor, en `claude_desktop_config.json`.
  32. - **VS Code**: en `.vscode/mcp.json`, dentro de `"servers"`, con `"type": "stdio"` y los mismos `command`, `args` y `env`.
  33. - **Codex**: en `~/.codex/config.toml`:
  34. ```toml
  35. [mcp_servers.funnelchat]
  36. command = "npx"
  37. args = ["-y", "@funnelchat-hq/mcp"]
  38. env = { FUNNELCHAT_API_KEY = "tu_clave" }
  39. ```
  40. Si tu cliente solo se conecta por HTTP, mira [Modo HTTP](#modo-http).
  41. ## Probarlo con el sandbox
  42. El [sandbox](https://www.npmjs.com/package/@funnelchat-hq/sandbox) imita la API en tu máquina, sin cuenta y sin mandar nada a WhatsApp. Arráncalo en una terminal y déjalo corriendo:
  43. ```bash
  44. npx @funnelchat-hq/sandbox
  45. ```
  46. Y apunta el MCP a él con `FUNNELCHAT_BASE_URL`. Contra el sandbox sirve cualquier clave bien formada:
  47. ```bash
  48. claude mcp add funnelchat-sandbox -e 'FUNNELCHAT_API_KEY=1|fc_live_sandbox' -e FUNNELCHAT_BASE_URL=http://127.0.0.1:4010 -- npx -y @funnelchat-hq/mcp
  49. ```
  50. Sin `FUNNELCHAT_BASE_URL`, el MCP va a la API real (`https://api.funnelchat.com`). El tool `status` dice siempre a qué URL está apuntando.
  51. ## Cómo se usa
  52. Le pides a tu asistente lo que quieres («manda un WhatsApp a…», «¿cuántas conversaciones sin leer tengo?») y él elige el tool. Empieza por `status`: dice qué números tienes conectados, si tienes webhooks y cuál es el siguiente paso.
  53. Cada tool agrupa las llamadas de un recurso y recibe `action`, `params` y, en lo que no se deshace, `confirm`:
  54. ```json
  55. { "action": "help" }
  56. { "action": "help", "params": { "action": "send" } }
  57. { "action": "send", "params": { "device_id": "dev_…", "phone": "5491122334455", "text": "Hola, Ana" } }
  58. ```
  59. `help` lista las acciones del tool; con `params.action` da los parámetros de una, con su ejemplo.
  60. <!-- TOOLS:INICIO (lo escribe npm run generate) -->
  61. Generado desde la spec del portal v0.7.0-49-g31766eb (sha256 `766230d4a8ce…`): 253 llamadas en 18 tools por recurso, más `status` y `search_docs`.
  62. | Tool | Qué hace | Acciones | Lecturas | No se deshacen |
  63. | --- | --- | ---: | ---: | ---: |
  64. | `numbers` | Números de WhatsApp: ver, crear por QR, editar, desconectar, salud, cola de mensajes y Conversions API. | 22 | 12 | 5 |
  65. | `connect_links` | Links para conectar un número por QR, tuyo o de un cliente, o para reconectarlo. | 4 | 2 | 1 |
  66. | `messages` | Mandar mensajes y plantillas, ver un mensaje, marcarlo leído, reaccionar, reenviar y mandar formularios. | 11 | 1 | 0 |
  67. | `conversations` | Conversaciones: mensajes con un contacto, listar, contar, marcar leídas y respuestas rápidas. | 13 | 8 | 1 |
  68. | `contacts` | Contactos: ver, crear, editar y borrar, su ventana de 24 h, sus notas y su puntaje. | 16 | 8 | 2 |
  69. | `tags` | Etiquetas: crearlas, editarlas y ponerlas o quitarlas a contactos. | 9 | 4 | 1 |
  70. | `custom_fields` | Campos personalizados y sus valores en cada contacto. | 8 | 3 | 1 |
  71. | `templates` | Plantillas de WhatsApp: ver, crear, editar, traer de Meta, métricas y borrar. | 7 | 3 | 1 |
  72. | `groups` | Grupos de WhatsApp: ver, seguir, mandarles un mensaje, participantes y canales. | 11 | 9 | 0 |
  73. | `group_actions` | Cambiar un grupo: crearlo, participantes, admins, nombre, foto, link y solicitudes. | 16 | 4 | 3 |
  74. | `campaigns` | Campañas de grupos, envíos programados y estadísticas, solo lectura. | 28 | 28 | 0 |
  75. | `broadcasts` | Difusiones: ver, buscar contactos, costo, estadísticas, cancelar y carpetas. | 16 | 10 | 3 |
  76. | `automations` | Flujos: verlos, sus contactos, cancelar una ejecución, pausar a un contacto y carpetas. | 16 | 11 | 2 |
  77. | `forms` | Formularios de WhatsApp: ver, crear, publicar, números, versiones y respuestas. | 18 | 9 | 1 |
  78. | `boards` | Tableros: etapas y mover contactos entre ellas. | 16 | 5 | 2 |
  79. | `tickets` | Tickets: ver, crear, editar, asignar, cerrar y reabrir. | 7 | 2 | 0 |
  80. | `webhooks` | Webhooks: crear, ver, editar, probar y borrar, sus entregas y los tipos de evento. | 8 | 4 | 1 |
  81. | `account` | Tu cuenta: datos, equipo, contactos activos, costos de Meta, ventas, dominios y alertas. | 27 | 20 | 1 |
  82. <!-- TOOLS:FIN -->
  83. `status` y `search_docs` completan los 20: `search_docs` busca en los textos del portal, que van dentro del paquete.
  84. ### Antes de llamar a la API
  85. - **Los parámetros se revisan contra la spec**: nombres, obligatorios, tipos y valores permitidos. Si sobra o falta algo, la llamada no sale y el error dice qué corregir, con el `help` de la acción. Un filtro mal escrito nunca devuelve la lista entera.
  86. - **Lo que no se deshace pide `confirm: true`**: borrar contactos, etiquetas o campos, cancelar una difusión, desconectar o borrar un número, sacar personas de un grupo… Sin `confirm`, el MCP no llama a la API y le pide al asistente que te pregunte primero. `help` marca esas acciones con «no se deshace».
  87. - **`--read-only`** deja solo las lecturas: no crea, no cambia ni borra nada, y tampoco da el QR de un número, porque con él se toma el control del número.
  88. ### Errores
  89. Un error vuelve marcado como error y con el cuerpo de la API: `status`, `error` (un código estable), `message`, y según el caso `errors` por campo o `retry_after` en segundos. Los errores del propio MCP, antes de llamar, son `unknown_params`, `invalid_params`, `confirmation_required`, `read_only` y `missing_api_key`.
  90. ## Modo HTTP
  91. Para hospedarlo o para clientes que solo hablan HTTP:
  92. ```bash
  93. npx -y @funnelchat-hq/mcp --http --port 3333
  94. ```
  95. - Escucha en `POST http://127.0.0.1:3333/mcp`, sin sesión.
  96. - Cada pedido trae su clave en `Authorization: Bearer <clave>` (o `X-API-Key`). Sin clave responde `401`: en este modo `FUNNELCHAT_API_KEY` no se usa.
  97. - Revisa `Host` y `Origin` de cada pedido, para que una página web no pueda usarlo (DNS rebinding). Por defecto acepta `127.0.0.1`, `localhost` y `[::1]` con su puerto.
  98. - Para escuchar fuera de tu máquina tienes que decir con qué nombre te llegan los pedidos:
  99. ```bash
  100. npx -y @funnelchat-hq/mcp --http --host 0.0.0.0 --port 3333 \
  101. --allowed-hosts mcp.tu-dominio.com --allowed-origins https://app.tu-dominio.com
  102. ```
  103. Ponlo detrás de un proxy con HTTPS: la clave viaja en cada pedido.
  104. - `GET /health` responde `{"ok": true}`.
  105. ## Opciones
  106. | Opción | Variable | Qué hace |
  107. | ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  108. | | `FUNNELCHAT_API_KEY` | La clave, en stdio. |
  109. | `--base-url <url>` | `FUNNELCHAT_BASE_URL` | El host de la API. Por defecto `https://api.funnelchat.com`; el sandbox, `http://127.0.0.1:4010`. Si termina en `/api/v1`, `/api` o `/v1`, se quita. `FUNNELCHAT_API_URL` también vale. |
  110. | `--read-only` | | Solo lecturas. |
  111. | `--http` | | HTTP en vez de stdio. |
  112. | `--host <host>` | | Dónde escucha en HTTP. Por defecto `127.0.0.1`. |
  113. | `--port <n>` | `PORT` | El puerto en HTTP. Por defecto `3333`. |
  114. | `--allowed-hosts <a,b>` | `MCP_ALLOWED_HOSTS` | Los `Host` que acepta en HTTP. |
  115. | `--allowed-origins <a,b>` | `MCP_ALLOWED_ORIGINS` | Los `Origin` que acepta en HTTP. |
  116. | `--version`, `--help` | | La versión y la ayuda. |
  117. ## La spec y las versiones
  118. Los tools salen de la spec que publica el portal (`spec/funnelchat.json`). De dónde salió, con su versión del portal y su `sha256`, está en `spec/procedencia.json`, que va dentro del paquete; `status` también la dice. Qué no se deshace, y qué se pierde, lo dice la spec con `x-fc-destructive`. Lo único escrito a mano es `diseno.json`: qué grupos del portal van a cada tool, algunos nombres de acción, lo poco que pide confirmación aunque la spec no lo marque y los ejemplos de las acciones principales.
  119. Una versión nueva de la spec es una versión nueva del paquete. Las acciones no cambian de nombre entre versiones: si una tuviera que cambiar, sale en una versión mayor.
  120. ## Desarrollo
  121. ```bash
  122. npm ci
  123. npm test # pruebas unitarias, sin red
  124. npx @funnelchat-hq/sandbox --port 4010 # en otra terminal
  125. SANDBOX_URL=http://127.0.0.1:4010 npm run test:e2e # contra el sandbox: stdio, HTTP, el ejemplo de cada acción y la prueba adversaria
  126. npm run test:pack # npm pack, instalarlo en un proyecto vacío y correrlo con npx
  127. npm run measure # cuántos tokens cargan los tools
  128. ```
  129. Con una spec nueva del portal:
  130. ```bash
  131. npm run generate -- --spec <ruta>/funnelchat.json # la copia a spec/, anota su procedencia y regenera generated/tabla.json
  132. npm run docs -- --portal <carpeta del portal construido> # regenera docs/indice.json, lo que busca search_docs
  133. ```
  134. Si el archivo no viene de un checkout del portal, di de dónde salió con `--source url=… --source portal_version=…`. `npm run generate:check` y `npm run docs:check` fallan si algo no está al día, si `docs/` ofrece lo que no existe o si la spec y la doc salieron de portales distintos; el CI corre los dos.
  135. Para publicar, sube un tag `vX.Y.Z` igual a la versión de `package.json` sobre un commit de `main`: `publish.yml` corre el CI y publica en npm con provenance.
  136. ## Licencia
  137. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.