Claude MCP Slack

A standalone GitHub Action that provides Slack MCP (Model Context Protocol) server functionality for Claude Code Action, enabling secure Slack image downloads and integrations.

Features

• 🔐 Secure Slack Integration: Authenticated access to Slack files using Bot User OAuth tokens

• 📁 Flexible File Management: Customizable download directories with security validation

• 🐳 Docker Support: Run locally or in containers with proper security constraints

• 🛡️ Security First: Input validation, path traversal prevention, and secure token handling

• 🧪 Comprehensive Testing: Unit, integration, and security test suites

• ⚡ Easy Integration: Drop-in compatibility with claude-code-action

Quick Start

Basic Usage

Advanced Configuration

Configuration

Inputs

Outputs

Environment Variables

The action sets up the following environment variables for the MCP server:

• SLACK_TOKEN: Your Slack Bot User OAuth Token

• DOWNLOAD_DIRECTORY: Resolved absolute path for downloads

Slack Bot Setup

1. Create a Slack App

1. Go to api.slack.com/apps

2. Click "Create New App" → "From scratch"

3. Name your app and select your workspace

2. Configure Bot Token Scopes

Under OAuth & Permissions, add these Bot Token Scopes:

3. Install to Workspace

1. Click "Install to Workspace"

2. Copy the "Bot User OAuth Token" (starts with xoxb-)

3. Add it to your repository secrets as SLACK_TOKEN

4. Example Bot Usage

Once configured, Claude can download Slack images:

Available MCP Tools

slack_image_download

Downloads images from Slack with authentication.

Parameters:

• url (required): Slack file URL (must start with https://files.slack.com/)

• filename (optional): Custom filename (will be sanitized)

Example:

slack_health_check

Checks the health and configuration of the Slack MCP server.

Example:

Security Features

Input Validation

• URL validation (must be Slack files domain)

• Token format verification

• Path traversal prevention

• Filename sanitization

Secure Execution

• Non-root container execution

• Read-only filesystem (except download directory)

• Resource limits (file size, timeout)

• No shell metacharacter injection

Token Security

• Environment variable isolation

• No token logging or exposure

• Secure token format validation

Development

Local Setup

Docker Development

Testing

Troubleshooting

Common Issues

"SLACK_TOKEN environment variable is required"

• Ensure your Slack token is properly set in repository secrets

• Verify the token starts with xoxb- or xoxp-

"URL must be a Slack file URL"

• Only URLs starting with https://files.slack.com/ are supported

• Ensure the URL is from a Slack file, not a regular message

"Permission denied" errors

• Check that your Slack bot has files:read scope

• Verify the bot is installed in the workspace where the file is located

Download failures

• Ensure the file hasn't been deleted from Slack

• Check that the file is accessible to your bot

• Verify network connectivity and firewall settings

Debug Mode

Enable debug logging by setting ACTIONS_STEP_DEBUG=true in your repository secrets.

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Make your changes

4. Add tests for new functionality

5. Ensure all tests pass (bun test)

6. Commit your changes (git commit -m 'Add amazing feature')

7. Push to the branch (git push origin feature/amazing-feature)

8. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices

• Add tests for all new features

• Update documentation for API changes

• Ensure security tests pass

• Use conventional commit messages

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation

• 🐛 Bug Reports

• 💬 Discussions

Related Projects

• claude-code-action - Official Claude GitHub Action

• MCP SDK - Model Context Protocol SDK