Spark Assistant for Slack - MCP Server

Un servidor de Model Context Protocol (MCP) para interactuar con áreas de trabajo de Slack, personalizado para Spark Assistant. Este servidor proporciona herramientas para listar canales, publicar mensajes, responder a hilos, añadir reacciones con emojis, recuperar el historial de canales, inspeccionar perfiles de usuario y probar la autenticación de la API de Slack.

⚡ Inicio rápido

1. Instala las dependencias y compila:

   npm install
   npm run build

2. Configura las variables de entorno: Copia .env.example a .env y completa tus credenciales de Slack:

   cp .env.example .env

   SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
   SLACK_TEAM_ID=T00000000

3. Ejecuta el servidor:

   # Standard stdio mode (for Claude Desktop / Antigravity / Cursor / Windsurf)
   node dist/index.js
   
   # HTTP mode on port 3000
   node dist/index.js --transport http --port 3000

Related MCP server: Slack MCP Server

🛠️ Herramientas disponibles

1. slack_auth_test

   • Prueba la autenticación del token del bot y recupera los detalles del área de trabajo conectada y del usuario del bot

   • Devuelve: nombre del área de trabajo, ID del equipo, ID de usuario del bot y URL de autenticación

2. slack_list_channels

   • Lista los canales públicos y privados de los que el bot es miembro, o los canales predefinidos en el área de trabajo

   • Entradas opcionales: limit (predeterminado: 100, máximo: 200), cursor (paginación)

3. slack_post_message

   • Publica un nuevo mensaje en un canal de Slack o en un mensaje directo a un usuario

   • Entradas obligatorias: channel_id, text

4. slack_reply_to_thread

   • Responde a un hilo de mensaje específico en Slack

   • Entradas obligatorias: channel_id, thread_ts, text

5. slack_add_reaction

   • Añade una reacción con emoji a un mensaje

   • Entradas obligatorias: channel_id, timestamp, reaction (nombre del emoji sin dos puntos)

6. slack_get_channel_history

   • Obtén los mensajes recientes de un canal

   • Entradas obligatorias: channel_id | Opcional: limit (predeterminado: 10)

7. slack_get_thread_replies

   • Obtén todas las respuestas de un hilo de mensaje

   • Entradas obligatorias: channel_id, thread_ts

8. slack_get_users

   • Obtén la lista de usuarios del área de trabajo con información básica del perfil

   • Entradas opcionales: cursor, limit (predeterminado: 100, máximo: 200)

9. slack_get_user_profile

   • Obtén información detallada del perfil de un usuario específico

   • Entradas obligatorias: user_id

Configuración del bot de Slack

Para usar este servidor MCP, necesitas crear una app de Slack y configurarla con los permisos necesarios:

1. Crea una app de Slack

• Visita la página de Apps de Slack

• Haz clic en "Create New App"

• Elige "From scratch"

• Pon nombre a tu app y selecciona tu área de trabajo

2. Configura los ámbitos del token del bot

Ve a "OAuth & Permissions" y añade estos ámbitos:

• channels:history - Ver mensajes y otro contenido en canales públicos

• channels:read - Ver información básica de los canales

• chat:write - Enviar mensajes como la app

• reactions:write - Añadir reacciones con emojis a los mensajes

• users:read - Ver usuarios y su información básica

• users.profile:read - Ver perfiles detallados de los usuarios

3. Instala la app en el área de trabajo

• Haz clic en "Install to Workspace" y autoriza la app

• Guarda el "Bot User OAuth Token" que empieza por xoxb-

4. Obtén tu ID de equipo

Obtén tu ID de equipo (empieza con una T) siguiendo esta guía

5. Añade el bot a canales (opcional)

Para que el bot pueda acceder a canales privados o publicar mensajes, es posible que tengas que invitarlo a canales específicos usando /invite @your-bot-name

Características

• Soporte de múltiples transportes: admite transportes stdio y HTTP Streamable

• SDK de MCP moderno: actualizado para usar el último SDK de MCP (v1.13.2) con APIs modernas

• Integración completa de Slack: conjunto completo de operaciones de Slack, incluyendo:

  • Listar canales (con soporte de canales predefinidos)

  • Publicar mensajes

  • Responder a hilos

  • Añadir reacciones

  • Obtener el historial de canales

  • Obtener respuestas de hilos

  • Listar usuarios

  • Obtener perfiles de usuario

Instalación

Desarrollo local

npm install
npm run build

Instalación global (NPM)

npm install -g @zencoderai/slack-mcp-server

Instalación con Docker

# Build the Docker image locally
docker build -t slack-mcp-server .

# Or pull from Docker Hub
docker pull zencoderai/slack-mcp:latest

# Or pull a specific version
docker pull zencoderai/slack-mcp:1.0.0

Configuración

Configura las siguientes variables de entorno:

export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_TEAM_ID="your-team-id"
export SLACK_CHANNEL_IDS="channel1,channel2,channel3"  # Optional: predefined channels
export AUTH_TOKEN="your-auth-token"  # Optional: Bearer token for HTTP authorization (Streamable HTTP transport only)

Uso

Opciones de línea de comandos

slack-mcp [options]

Options:
  --transport <type>     Transport type: 'stdio' or 'http' (default: stdio)
  --port <number>        Port for HTTP server when using Streamable HTTP transport (default: 3000)
  --token <token>        Bearer token for HTTP authorization (optional, can also use AUTH_TOKEN env var)
  --help, -h             Show this help message

Ejemplos de uso local

Uso del comando slack-mcp (después de la instalación global)

# Use stdio transport (default)
slack-mcp

# Use stdio transport explicitly
slack-mcp --transport stdio

# Use Streamable HTTP transport on default port 3000
slack-mcp --transport http

# Use Streamable HTTP transport on custom port
slack-mcp --transport http --port 8080

# Use Streamable HTTP transport with custom auth token
slack-mcp --transport http --token mytoken

# Use Streamable HTTP transport with auth token from environment variable
AUTH_TOKEN=mytoken slack-mcp --transport http

Uso de node directamente (para desarrollo)

# Use stdio transport (default)
node dist/index.js

# Use stdio transport explicitly
node dist/index.js --transport stdio

# Use Streamable HTTP transport on default port 3000
node dist/index.js --transport http

# Use Streamable HTTP transport on custom port
node dist/index.js --transport http --port 8080

# Use Streamable HTTP transport with custom auth token
node dist/index.js --transport http --token mytoken

# Use Streamable HTTP transport with auth token from environment variable
AUTH_TOKEN=mytoken node dist/index.js --transport http

Ejemplos de uso con Docker

Uso de Docker directamente

# Run with stdio transport (default)
docker run --rm \
  -e SLACK_BOT_TOKEN="xoxb-your-bot-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  zencoderai/slack-mcp:latest

# Run with HTTP transport on port 3000
docker run --rm -p 3000:3000 \
  -e SLACK_BOT_TOKEN="xoxb-your-bot-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  zencoderai/slack-mcp:latest --transport http

# Run with HTTP transport on custom port
docker run --rm -p 8080:8080 \
  -e SLACK_BOT_TOKEN="xoxb-your-bot-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  zencoderai/slack-mcp:latest --transport http --port 8080

# Run with custom auth token
docker run --rm -p 3000:3000 \
  -e SLACK_BOT_TOKEN="xoxb-your-bot-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  -e AUTH_TOKEN="mytoken" \
  zencoderai/slack-mcp:latest --transport http

Uso de Docker Compose

Crea un archivo docker-compose.yml:

version: '3.8'

services:
  slack-mcp:
    # Use published image:
    image: zencoderai/slack-mcp:latest
    # Or build locally:
    # build: .
    environment:
      - SLACK_BOT_TOKEN=xoxb-your-bot-token
      - SLACK_TEAM_ID=your-team-id
      - SLACK_CHANNEL_IDS=channel1,channel2,channel3  # Optional
      - AUTH_TOKEN=your-auth-token  # Optional for HTTP transport
    ports:
      - "3000:3000"  # Only needed for HTTP transport
    command: ["--transport", "http"]  # Optional: specify transport type
    restart: unless-stopped

A continuación, ejecuta:

# Start the service
docker compose up -d

# View logs
docker compose logs -f slack-mcp

# Stop the service
docker compose down

Tipos de transporte

Transporte Stdio

• Caso de uso: herramientas de línea de comandos e integraciones directas

• Comunicación: flujos estándar de entrada/salida

• Predeterminado: Sí

Transporte HTTP Streamable

• Caso de uso: servidores remotos e integraciones basadas en web

• Comunicación: peticiones HTTP POST con flujos opcionales de Server-Sent Events

• Características:

  • Gestión de sesiones

  • Comunicación bidireccional

  • Conexiones reanudables

  • Endpoints de API RESTful

  • Autenticación con token Bearer

Autenticación (solo transporte HTTP Streamable)

Al usar el transporte HTTP Streamable, el servidor admite autenticación con token Bearer:

1. Línea de comandos: usa --token <token> para especificar un token personalizado

2. Variable de entorno: configura AUTH_TOKEN=<token> como respaldo

3. Generado automáticamente: si no se proporciona ninguno, se genera un token aleatorio

La opción de línea de comandos tiene prioridad sobre la variable de entorno. Incluye el token en las peticiones HTTP usando la cabecera Authorization: Bearer <token>.

Solución de problemas

Si encuentras errores de permisos, verifica que:

1. Todos los ámbitos necesarios estén añadidos a tu app de Slack

2. La app esté correctamente instalada en tu área de trabajo

3. Los tokens y el ID del área de trabajo estén copiados correctamente en tu configuración

4. La app se haya añadido a los canales a los que necesita acceder

Desarrollo

Compilar

npm run build

Modo de observación

npm run watch

Endpoints de API (transporte HTTP Streamable)

Al usar el transporte HTTP Streamable, el servidor expone los siguientes endpoints:

• POST /mcp - Comunicación de cliente a servidor

• GET /mcp - Notificaciones de servidor a cliente (flujos de Server-Sent Events)

• DELETE /mcp - Terminación de sesión

Cambios respecto a la versión anterior

• SDK de MCP actualizado: se actualizó de v1.0.1 a v1.13.2

• API moderna: se migró de la clase Server de bajo nivel a la clase McpServer de alto nivel

• Validación con Zod: se añadió una validación de esquemas adecuada usando Zod

• Flexibilidad de transporte: se añadió soporte para el transporte HTTP Streamable

• Interfaz de línea de comandos: se añadieron argumentos CLI para la selección de transporte

• Gestión de sesiones: se implementó un manejo adecuado de sesiones para el transporte HTTP

• Mejor manejo de errores: se mejoraron el manejo de errores y el registro de actividad