https://github.com/duolingo/slack-mcp
OAuth-based multi-user Slack MCP server with HTTP transport
https://github.com/duolingo/slack-mcp
http mcp model-context-protocol oauth python slack
Last synced: about 1 month ago
JSON representation
OAuth-based multi-user Slack MCP server with HTTP transport
- Host: GitHub
- URL: https://github.com/duolingo/slack-mcp
- Owner: duolingo
- License: apache-2.0
- Created: 2025-11-20T18:33:58.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-03-19T17:46:59.000Z (3 months ago)
- Last Synced: 2026-03-20T09:32:20.093Z (3 months ago)
- Topics: http, mcp, model-context-protocol, oauth, python, slack
- Language: Python
- Homepage:
- Size: 327 KB
- Stars: 6
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Slack MCP Server
A read-only MCP (Model Context Protocol) server for Slack with OAuth 2.1 authentication.
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
## Demo
https://github.com/user-attachments/assets/211bd428-209f-461a-b9a1-9cc85fd7c438
### Available Tools
- `slack_get_channel_messages` - Retrieve messages from channels
- `slack_get_thread_replies` - Get conversation thread replies
- `slack_search_messages` - Advanced message search with filters
- `slack_get_users` - List workspace users or get specific profiles
- `slack_get_channels` - List channels or get detailed info
## Quick Start
### 1. Create Slack App
1. Visit [Slack API Apps](https://api.slack.com/apps) and create a new app
2. Under **App Credentials**, copy your `Client ID` and `Client Secret`
3. Navigate to **OAuth & Permissions** and add these [**User Token Scopes**](https://docs.slack.dev/reference/scopes/): `channels:history` `groups:history` `im:history` `mpim:history` `channels:read` `groups:read` `im:read` `mpim:read` `users:read` `users:read.email` `search:read`
4. Add **Redirect URL** under **OAuth & Permissions**:
- For local testing: Use an HTTPS proxy like ngrok (E.g: `https://abc123.ngrok.io/oauth2callback`). See local development setup below.
- For production: `https://your-domain.com/oauth2callback`
### 2. Installation
```bash
uv sync
```
### 3. Local Development Setup (HTTPS Proxy)
Slack requires HTTPS for OAuth callbacks. For local development, use ngrok or a similar HTTPS proxy:
```bash
# Visit https://ngrok.com/ to download ngrok and start the proxy
ngrok http 8001
```
Copy the HTTPS forwarding URL (e.g., `https://abc123.ngrok.io/oauth2callback`) and add it as a Redirect URL in your Slack app settings.
### 4. Configuration
Set required environment variables:
```bash
export SLACK_CLIENT_ID="your_client_id"
export SLACK_CLIENT_SECRET="your_client_secret"
# Use https://your-domain.com for production.
export SLACK_MCP_BASE_URI="http://localhost"
# Use https://your-domain.com for production.
export SLACK_EXTERNAL_URL="https://abc123.ngrok.io"
# Optional, if you want to run the MCP server on a different port.
export SLACK_MCP_PORT=8001
```
### 5. Run the Server
```bash
uv run python main.py
```
The server will start on `http://localhost:8001` by default. Make sure your ngrok proxy is running alongside it for OAuth to work.
### 6. Configure Your MCP Client
Add to your MCP client configuration (e.g. ~/.cursor/mcp.json for Cursor):
```json
{
"mcpServers": {
"slack": { "url": "http://localhost:8001/mcp", "transport": "http" }
}
}
```
### 7. Authenticate
Authentication happens automatically via OAuth 2.1 when your MCP client first connects. Your client will open a browser window for Slack authorization — approve access and you're ready to go.
## Deployment
For production deployment, you can run it inside docker:
```bash
docker build -t slack-mcp .
docker run -p 8001:8001 \
-e SLACK_CLIENT_ID="your_client_id" \
-e SLACK_CLIENT_SECRET="your_client_secret" \
-e SLACK_MCP_BASE_URI="https://your-domain.com" \
-e SLACK_EXTERNAL_URL="https://your-domain.com" \
slack-mcp
```
## Development
Run tests with `uv run pytest`.
## License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
Duolingo is hiring! Apply at https://www.duolingo.com/careers