Slack MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Slack workspaces through OAuth 2.0 authentication.

Features

• 🔐 OAuth 2.0 Authentication: Secure Slack OAuth flow with automatic token management
• 🚀 FastMCP Framework: Built with the official MCP SDK's FastMCP framework
• 💾 Token Persistence: Tokens are saved locally or in DynamoDB for cloud deployments
• 📱 Slack Integration: Post messages and list channels in Slack workspaces
• 🔄 Dynamic Client Registration: Supports VSCode MCP extension and other clients
• ☁️ GitHub + App Runner: Deploy directly from GitHub with AWS App Runner

Prerequisites

• Python 3.11+
• Slack App with OAuth 2.0 configured
• uv (Python package manager)

Quick Start

1. Slack App Configuration

1. Create a new Slack App at https://api.slack.com/apps
2. Add OAuth Scopes in "OAuth & Permissions":
   • chat:write - Post messages
   • channels:read - List channels
3. Add Redirect URLs:
   • Local: http://localhost:8080/slack/callback
   • Production: https://your-domain.com/slack/callback
4. Copy the Client ID and Client Secret

2. Installation

# Clone the repository
git clone https://github.com/miyatsuki/study-slack-remote-mcp.git
cd study-slack-remote-mcp

# Install dependencies using uv
uv sync

3. Configuration

Create a .env file:

# Required: Slack OAuth credentials
SLACK_CLIENT_ID=your_client_id
SLACK_CLIENT_SECRET=your_client_secret

# Optional: Service base URL (for production deployments)
# SERVICE_BASE_URL=https://your-apprunner-url.awsapprunner.com

4. Run the Server

# Start the server
uv run python server.py

# Or run in background
nohup uv run python server.py > server.log 2>&1 &

Usage

With VSCode MCP Extension

1. Install the MCP extension for VSCode
2. Connect to the server URL: http://localhost:8080/mcp/
3. The OAuth flow will start automatically when you first use a tool

With Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "slack": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/slack-mcp-server",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Available Tools

1. list_channels: Get a list of Slack channels

   Returns: Dictionary mapping channel names to IDs
   

2. post_message: Post a message to a Slack channel

   Args:
   - channel_id: Channel ID (required)
   - text: Message text (required)
   
   Returns: Success/failure message
   

3. get_auth_status: Check authentication status

   Returns: Current authentication state and session info
   

Authentication Flow

1. When a tool is first used, the OAuth flow automatically starts
2. A browser window opens for Slack authorization
3. After authorization, the token is saved for future use
4. Subsequent requests use the cached token

Authentication

The server uses FastMCP's built-in OAuth 2.0 support with dynamic client registration. This allows compatibility with various MCP clients including VSCode's MCP extension.

Token Management

• OAuth tokens are mapped between MCP tokens and Slack tokens internally
• Tokens are persisted locally in memory (or DynamoDB in cloud)
• OAuth flow starts automatically when tools are first used
• Dynamic client registration supported for VSCode and other clients

Port Configuration

The server uses a single port:

• 8080: MCP server endpoint (includes health check and OAuth callback routes)

AWS App Runner Deployment (ECR-based)

The project uses ECR-based deployment with AWS App Runner for production:

# First, set up AWS Systems Manager parameters:
aws ssm put-parameter --name "/slack-mcp/dev/client-id" --value "your-client-id" --type "String"
aws ssm put-parameter --name "/slack-mcp/dev/client-secret" --value "your-secret" --type "SecureString"
aws ssm put-parameter --name "/slack-mcp/dev/service-base-url" --value "https://your-apprunner-url.awsapprunner.com" --type "String"

# Build and push Docker image to ECR:
./build-and-push.sh

# Create App Runner service (if not exists) or update existing service
aws apprunner update-service --service-arn <your-service-arn> --source-configuration '...'

App Runner provides:

• Deployment from ECR with pre-built Docker images
• Built-in HTTPS with automatic certificates
• Manual deployment control (auto-deploy disabled by default)
• Auto-scaling and simplified management
• Avoids Python 3.11 build issues with App Runner's source code deployment

Project Structure

study-slack-remote-mcp/
├── server.py               # Main MCP server using FastMCP framework
├── slack_oauth_provider.py # Slack OAuth provider implementation
├── storage_interface.py    # Storage abstraction (local/cloud)
├── storage_dynamodb.py     # DynamoDB storage for AWS
├── token_storage.py        # Local file-based token storage
├── Dockerfile             # Docker container configuration
├── build-and-push.sh      # ECR deployment script
├── requirements.txt       # Python dependencies for Docker
├── pyproject.toml         # Project dependencies
├── uv.lock               # Locked dependencies
├── tests/                 # Unit tests
├── infrastructure/        # AWS CDK deployment code
├── CLAUDE.md             # Development guidelines
└── .env                  # Environment variables (create from .env.example)

Development

Testing

# Check server health
curl http://localhost:8080/health

# Test with MCP client
mcp run uv --directory /path/to/study-slack-remote-mcp run python server.py

Debugging

Enable debug logging by checking server.log:

tail -f server.log

Troubleshooting

Port Already in Use

# Check what's using port 8080
lsof -i :8080

# Kill process using port 8080 if needed
kill -9 $(lsof -ti:8080)

OAuth Errors

1. bad_redirect_uri: Ensure the redirect URL in Slack app matches exactly:

   • Must include the full path: http://localhost:8080/slack/callback
   • Port must be 8080 (MCP server port)

2. invalid_client_id: Verify SLACK_CLIENT_ID in .env

3. Token not found: Complete OAuth by authorizing in browser

Security Considerations

• OAuth tokens are mapped between MCP tokens and Slack tokens
• Tokens stored in memory locally, DynamoDB in production
• Dynamic client registration supports various MCP clients
• OAuth callbacks use HTTPS in production (App Runner)

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the guidelines in CLAUDE.md
4. Submit a pull request

License

MIT License - see LICENSE file for details

References

• MCP Documentation
• MCP Python SDK
• Slack API Documentation