Slack MCP Server

# 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 ```bash # 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: ```bash # 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 ```bash # 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` ```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: ```bash # 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 ```bash # 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`: ```bash tail -f server.log ``` ## Troubleshooting ### Port Already in Use ```bash # 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](https://modelcontextprotocol.io) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Slack API Documentation](https://api.slack.com)