Claude MCP Slack

Una Acción GitHub independiente que proporciona funcionalidad de servidor Slack MCP (Model Context Protocol) para la Acción Claude Code, permitiendo descargas e integraciones seguras de imágenes Slack.

Características

• 🔐 Integración segura de Slack: Acceso autenticado a los archivos de Slack utilizando tokens OAuth de Bot User
• 📁 Gestión flexible de archivos: Directorios de descarga personalizables con validación de seguridad
• 🐳 Compatibilidad con Docker: Ejecuta localmente o en contenedores con las restricciones de seguridad adecuadas
• 🛡️ Security First: Validación de entrada, prevención de path traversal y gestión segura de tokens
• pruebas exhaustivas: Suites de pruebas unitarias, de integración y de seguridad
• fácil integración: Compatibilidad directa con claude-code-action

Inicio rápido

Uso básico

name: Ejemplo de flujo de trabajo on: issues: types: [abierto] issue_comment: tipos: [created] jobs: claude-response: runs-on: ubuntu-latest steps: - name: Setup Slack MCP uses: atlasfutures/claude-mcp-slack@v1 with: slack_token: ${{ secrets.SLACK_TOKEN }} id: slack-mcp - name: Claude Code Action uses: anthropics/claude-code-action@main with: mcp_config: ${{ steps.slack-mcp.outputs.mcp_config }} anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Configuración avanzada

- name: Setup Slack MCP uses: atlasfutures/claude-mcp-slack@v1 with: slack_token: ${{ secrets.SLACK_TOKEN }} download_directory: "./slack-assets" id: slack-mcp - name: Claude Code Action with Multiple MCP Servers uses: anthropics/claude-code-action@main with: mcp_config: | { "mcpServers": { "slack": ${{ steps.slack-mcp.outputs.mcp_config }}.mcpServers.slack, "custom": { "command": "node", "args": ["custom-server.js"], "env": {"API_KEY": "${{ secrets.CUSTOM_API_KEY }}" } } } anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Configuración

Entradas

Salidas

Variables de entorno

La acción configura las siguientes variables de entorno para el servidor MCP:

• SLACK_TOKEN: Tu token OAuth de usuario del bot de Slack
• DOWNLOAD_DIRECTORY: Ruta absoluta resuelta para las descargas

Configuración del Bot Slack

1. Crear una aplicación Slack

1. Ir a api.slack.com/apps
2. Haz clic en "Crear nueva app" → "Desde cero"
3. Ponle un nombre a tu app y selecciona tu espacio de trabajo

2. Configura los ámbitos del token de bots

En OAuth & Permissions, añade estos Bot Token Scopes:

files:read # Leer contenido de archivos y metadatos

3. Instalar en el espacio de trabajo

1. Haga clic en "Instalar en el espacio de trabajo
2. Copia el "Bot User OAuth Token" (empieza por xoxb-)
3. Añádelo a los secretos de tu repositorio como SLACK_TOKEN

4. Ejemplo de uso del bot

Una vez configurado, Claude puede descargar imágenes de Slack:

@claude Analiza esta captura de pantalla de nuestro canal de Slack: https://files.slack.com/files-tmb/T05EFSVDCLR-F08TC9CP9B8/screenshot_720.png

Herramientas MCP disponibles

slack_image_download

Descarga imágenes de Slack con autenticación.

Parámetros:

• url (obligatorio): URL del archivo de Slack (debe empezar por https://files.slack.com/)
• filename (opcional): Nombre de archivo personalizado (será desinfectado)

Ejemplo:

{ "tool": "slack_image_download", "arguments": { "url": "https://files.slack.com/files-tmb/T05EFSVDCLR-F08TC9CP9B8/screenshot_720.png", "filename": "screenshot.png" } }

slack_health_check

Comprueba el estado y la configuración del servidor Slack MCP.

Ejemplo:

{ "tool": "slack_health_check", "arguments": {} }

Funciones de seguridad

Validación de entrada

• Validación de URL (debe ser el dominio de los archivos de Slack)
• Verificación del formato del token
• Prevención de rutas
• Saneamiento de nombres de archivo

Ejecución segura

• Ejecución de contenedor no root
• Sistema de archivos de sólo lectura (excepto directorio de descarga)
• Límites de recursos (tamaño de archivo, tiempo de espera)
• Sin inyección de metacaracteres del shell

Seguridad de tokens

• Aislamiento de variables de entorno
• Sin registro ni exposición de tokens
• Validación segura del formato del token

Desarrollo

Configuración local

# Clonar repositorio git clone https://github.com/atlasfutures/claude-mcp-slack.git cd claude-mcp-slack Instalar dependencias bun install Ejecutar pruebas bun test Comprobación tipográfica bun run typecheck Formatear código bun run format

Desarrollo Docker

# Construir y ejecutar con docker-compose docker-compose up claude-mcp-slack-dev # O construir manualmente docker build -t claude-mcp-slack . docker run -e SLACK_TOKEN=su-token claude-mcp-slack

Pruebas

# Ejecutar todas las pruebas bun test # Ejecutar conjuntos de pruebas específicos bun run test:unit bun run test:integration bun run test:security # Ejecutar con cobertura bun test --coverage

Solución de problemas

Problemas comunes

"Se requiere la variable de entorno SLACK_TOKEN"

• Asegúrese de que su token de Slack está correctamente configurado en los secretos del repositorio
• Compruebe que el token empieza por xoxb- o xoxp-

"La URL debe ser una URL de archivo Slack"

• Sólo se admiten URLs que empiecen por https://files.slack.com/
• Asegúrese de que la URL es de un archivo Slack, no de un mensaje normal

"Errores de "Permiso denegado

• Comprueba que tu bot de Slack tiene alcance files:read
• Compruebe que el bot está instalado en el espacio de trabajo donde se encuentra el archivo

Fallos de descarga

• Compruebe que el archivo no se ha eliminado de Slack
• Comprueba que tu bot puede acceder al archivo
• Comprueba la conectividad de la red y la configuración del cortafuegos

Modo de depuración

Habilita el registro de depuración estableciendo ACTIONS_STEP_DEBUG=true en los secretos de tu repositorio.

Contribuir

1. Fork el repositorio
2. Cree una rama de características(git checkout -b feature/amazing-feature)
3. Haga sus cambios
4. Añada pruebas para la nueva funcionalidad
5. Asegúrese de que todas las pruebas pasan(bun test)
6. Confirmar los cambios(git commit -m 'Añadir característica asombrosa')
7. Empuja a la rama(git push origin feature/amazing-feature)
8. Abrir una Pull Request

Pautas de desarrollo

• Sigue las mejores prácticas de TypeScript
• Añade pruebas para todas las nuevas funciones
• Actualizar la documentación de los cambios en la API
• Asegúrese de que se superan las pruebas de seguridad
• Utilice mensajes de confirmación convencionales

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

Soporte

• 📖 Documentación
• 🐛 Informes de errores
• 💬 Discusiones

Proyectos Relacionados

• claude-code-action - Acción oficial de Claude en GitHub
• MCP SDK - SDK de protocolo de contexto de modelo