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

name: Example Workflow
on:
  issues:
    types: [opened]
  issue_comment:
    types: [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 }}

Advanced Configuration

- 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 }}

Configuration

Inputs

Input	Description	Required	Default
slack_token	Slack Bot User OAuth Token (xoxb-*)	✅	-
download_directory	Directory for downloaded files	❌	"."

Outputs

Output	Description
mcp_config	JSON configuration for claude-code-action
server_executable	Path to the Slack MCP server

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:

files:read      # Read file content and metadata

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:

@claude Please analyze this screenshot from our Slack channel: https://files.slack.com/files-tmb/T05EFSVDCLR-F08TC9CP9B8/screenshot_720.png

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:

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

slack_health_check

Checks the health and configuration of the Slack MCP server.

Example:

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

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

# Clone repository
git clone https://github.com/atlasfutures/claude-mcp-slack.git
cd claude-mcp-slack

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Format code
bun run format

Docker Development

# Build and run with docker-compose
docker-compose up claude-mcp-slack-dev

# Or build manually
docker build -t claude-mcp-slack .
docker run -e SLACK_TOKEN=your-token claude-mcp-slack

Testing

# Run all tests
bun test

# Run specific test suites
bun run test:unit
bun run test:integration
bun run test:security

# Run with coverage
bun test --coverage

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