Back to search
funnelchat-api-mcp
MCP serverGitHub
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
Markdown
[](/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
- # @funnelchat-hq/mcp
- 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.
- 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.
- ## Antes de empezar
- - Node 20.11 o más.
- - 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.
- ## Instalarlo
- ### Claude Code
- ```bash
- claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp
- ```
- Para que solo pueda leer, agrega `--read-only` al final:
- ```bash
- claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp --read-only
- ```
- ### Cursor
- En `.cursor/mcp.json` (de tu proyecto) o en `~/.cursor/mcp.json`:
- ```json
- {
- "mcpServers": {
- "funnelchat": {
- "command": "npx",
- "args": ["-y", "@funnelchat-hq/mcp"],
- "env": { "FUNNELCHAT_API_KEY": "tu_clave" }
- }
- }
- }
- ```
- ### Otros clientes MCP
- Todos piden lo mismo: el comando `npx -y @funnelchat-hq/mcp` y la variable `FUNNELCHAT_API_KEY`.
- - **Claude Desktop**: el mismo bloque `mcpServers` de Cursor, en `claude_desktop_config.json`.
- - **VS Code**: en `.vscode/mcp.json`, dentro de `"servers"`, con `"type": "stdio"` y los mismos `command`, `args` y `env`.
- - **Codex**: en `~/.codex/config.toml`:
- ```toml
- [mcp_servers.funnelchat]
- command = "npx"
- args = ["-y", "@funnelchat-hq/mcp"]
- env = { FUNNELCHAT_API_KEY = "tu_clave" }
- ```
- Si tu cliente solo se conecta por HTTP, mira [Modo HTTP](#modo-http).
- ## Probarlo con el sandbox
- 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:
- ```bash
- npx @funnelchat-hq/sandbox
- ```
- Y apunta el MCP a él con `FUNNELCHAT_BASE_URL`. Contra el sandbox sirve cualquier clave bien formada:
- ```bash
- 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
- ```
- 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.
- ## Cómo se usa
- 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.
- Cada tool agrupa las llamadas de un recurso y recibe `action`, `params` y, en lo que no se deshace, `confirm`:
- ```json
- { "action": "help" }
- { "action": "help", "params": { "action": "send" } }
- { "action": "send", "params": { "device_id": "dev_…", "phone": "5491122334455", "text": "Hola, Ana" } }
- ```
- `help` lista las acciones del tool; con `params.action` da los parámetros de una, con su ejemplo.
- <!-- TOOLS:INICIO (lo escribe npm run generate) -->
- 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`.
- | Tool | Qué hace | Acciones | Lecturas | No se deshacen |
- | --- | --- | ---: | ---: | ---: |
- | `numbers` | Números de WhatsApp: ver, crear por QR, editar, desconectar, salud, cola de mensajes y Conversions API. | 22 | 12 | 5 |
- | `connect_links` | Links para conectar un número por QR, tuyo o de un cliente, o para reconectarlo. | 4 | 2 | 1 |
- | `messages` | Mandar mensajes y plantillas, ver un mensaje, marcarlo leído, reaccionar, reenviar y mandar formularios. | 11 | 1 | 0 |
- | `conversations` | Conversaciones: mensajes con un contacto, listar, contar, marcar leídas y respuestas rápidas. | 13 | 8 | 1 |
- | `contacts` | Contactos: ver, crear, editar y borrar, su ventana de 24 h, sus notas y su puntaje. | 16 | 8 | 2 |
- | `tags` | Etiquetas: crearlas, editarlas y ponerlas o quitarlas a contactos. | 9 | 4 | 1 |
- | `custom_fields` | Campos personalizados y sus valores en cada contacto. | 8 | 3 | 1 |
- | `templates` | Plantillas de WhatsApp: ver, crear, editar, traer de Meta, métricas y borrar. | 7 | 3 | 1 |
- | `groups` | Grupos de WhatsApp: ver, seguir, mandarles un mensaje, participantes y canales. | 11 | 9 | 0 |
- | `group_actions` | Cambiar un grupo: crearlo, participantes, admins, nombre, foto, link y solicitudes. | 16 | 4 | 3 |
- | `campaigns` | Campañas de grupos, envíos programados y estadísticas, solo lectura. | 28 | 28 | 0 |
- | `broadcasts` | Difusiones: ver, buscar contactos, costo, estadísticas, cancelar y carpetas. | 16 | 10 | 3 |
- | `automations` | Flujos: verlos, sus contactos, cancelar una ejecución, pausar a un contacto y carpetas. | 16 | 11 | 2 |
- | `forms` | Formularios de WhatsApp: ver, crear, publicar, números, versiones y respuestas. | 18 | 9 | 1 |
- | `boards` | Tableros: etapas y mover contactos entre ellas. | 16 | 5 | 2 |
- | `tickets` | Tickets: ver, crear, editar, asignar, cerrar y reabrir. | 7 | 2 | 0 |
- | `webhooks` | Webhooks: crear, ver, editar, probar y borrar, sus entregas y los tipos de evento. | 8 | 4 | 1 |
- | `account` | Tu cuenta: datos, equipo, contactos activos, costos de Meta, ventas, dominios y alertas. | 27 | 20 | 1 |
- <!-- TOOLS:FIN -->
- `status` y `search_docs` completan los 20: `search_docs` busca en los textos del portal, que van dentro del paquete.
- ### Antes de llamar a la API
- - **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.
- - **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».
- - **`--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.
- ### Errores
- 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`.
- ## Modo HTTP
- Para hospedarlo o para clientes que solo hablan HTTP:
- ```bash
- npx -y @funnelchat-hq/mcp --http --port 3333
- ```
- - Escucha en `POST http://127.0.0.1:3333/mcp`, sin sesión.
- - 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.
- - 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.
- - Para escuchar fuera de tu máquina tienes que decir con qué nombre te llegan los pedidos:
- ```bash
- npx -y @funnelchat-hq/mcp --http --host 0.0.0.0 --port 3333 \
- --allowed-hosts mcp.tu-dominio.com --allowed-origins https://app.tu-dominio.com
- ```
- Ponlo detrás de un proxy con HTTPS: la clave viaja en cada pedido.
- - `GET /health` responde `{"ok": true}`.
- ## Opciones
- | Opción | Variable | Qué hace |
- | ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | | `FUNNELCHAT_API_KEY` | La clave, en stdio. |
- | `--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. |
- | `--read-only` | | Solo lecturas. |
- | `--http` | | HTTP en vez de stdio. |
- | `--host <host>` | | Dónde escucha en HTTP. Por defecto `127.0.0.1`. |
- | `--port <n>` | `PORT` | El puerto en HTTP. Por defecto `3333`. |
- | `--allowed-hosts <a,b>` | `MCP_ALLOWED_HOSTS` | Los `Host` que acepta en HTTP. |
- | `--allowed-origins <a,b>` | `MCP_ALLOWED_ORIGINS` | Los `Origin` que acepta en HTTP. |
- | `--version`, `--help` | | La versión y la ayuda. |
- ## La spec y las versiones
- 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.
- 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.
- ## Desarrollo
- ```bash
- npm ci
- npm test # pruebas unitarias, sin red
- npx @funnelchat-hq/sandbox --port 4010 # en otra terminal
- 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
- npm run test:pack # npm pack, instalarlo en un proyecto vacío y correrlo con npx
- npm run measure # cuántos tokens cargan los tools
- ```
- Con una spec nueva del portal:
- ```bash
- npm run generate -- --spec <ruta>/funnelchat.json # la copia a spec/, anota su procedencia y regenera generated/tabla.json
- npm run docs -- --portal <carpeta del portal construido> # regenera docs/indice.json, lo que busca search_docs
- ```
- 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.
- 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.
- ## Licencia
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.