# Quick Start Guide
Get your Slack MCP server running in 5 minutes.
## Prerequisites
- Node.js 18+ installed
- pnpm installed (`npm install -g pnpm`)
- A Slack workspace where you can install apps
## Step 1: Create Slack App (5 minutes)
1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **"Create New App"** → **"From scratch"**
3. Name it (e.g., "My MCP Bot") and select your workspace
4. Go to **"OAuth & Permissions"** → **"Bot Token Scopes"**
5. Add these scopes:
- `chat:write`
- `channels:history`
- `channels:read`
6. Go to **"OAuth & Permissions"** → **"Redirect URLs"**
7. Add: `http://localhost:8080/slack/oauth/callback`
8. Click **"Save URLs"**
9. Go to **"Basic Information"** → **"App Credentials"**
10. Copy your **Client ID** and **Client Secret**
## Step 2: Configure Server (2 minutes)
1. Clone/download this repository
2. Install dependencies:
```bash
pnpm install
```
3. Copy the example environment file:
```bash
cp env.example .env
```
4. Edit `.env` and set these values:
```bash
SLACK_CLIENT_ID=your_client_id_here
SLACK_CLIENT_SECRET=your_client_secret_here
SLACK_REDIRECT_URI=http://localhost:8080/slack/oauth/callback
SLACK_SCOPES=chat:write,channels:history,channels:read
AFFINITYBOTS_MCP_API_KEY=test-key-123
```
## Step 3: Start Server (1 minute)
```bash
pnpm dev
```
You should see:
```
{"level":"info","msg":"Slack MCP listening","PORT":8080,"HOST":"0.0.0.0"}
```
## Step 4: Install to Slack (1 minute)
1. Open your browser to: `http://localhost:8080/slack/install`
2. Click **"Allow"** on the Slack authorization page
3. You'll be redirected back with a success message
## Step 5: Test It (1 minute)
### Get Your Team ID
Check the server logs for a line like:
```json
{"level":"info","team_id":"T01234567","msg":"Slack workspace connected successfully"}
```
Copy the `team_id` value (starts with `T`).
### Test with curl
```bash
# Initialize MCP session
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer test-key-123" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "test", "version": "1.0.0"}
}
}'
```
Save the `Mcp-Session-Id` from the response headers.
### List Channels
```bash
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer test-key-123" \
-H "Mcp-Session-Id: YOUR_SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "slack_list_channels",
"arguments": {"team_id": "T01234567"}
}
}'
```
You should see a list of channels!
## What's Next?
### For Development
- Read [README.md](./README.md) for full documentation
- Explore other MCP tools (`slack_post_message`, `slack_get_channel_history`)
- Add more Slack scopes for additional functionality
### For Production
- Read [IMPLEMENTATION.md](./IMPLEMENTATION.md) for deployment guide
- Set up HTTPS (required by Slack)
- Replace `InMemoryInstallStore` with persistent storage
- Use [PRODUCTION_CHECKLIST.md](./PRODUCTION_CHECKLIST.md)
## Troubleshooting
### "Missing Slack OAuth env vars"
- Check your `.env` file has `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_REDIRECT_URI`
### "Origin not allowed"
- This is normal for local development without CORS restrictions
- For production, set `ALLOWED_ORIGINS` in `.env`
### "No Slack installation found"
- Complete the OAuth flow first by visiting `/slack/install`
### "Unauthorized"
- Make sure you're sending `Authorization: Bearer test-key-123` header
- The value must match `AFFINITYBOTS_MCP_API_KEY` in `.env`
## Need Help?
1. Check [README.md](./README.md) for detailed documentation
2. Check [IMPLEMENTATION.md](./IMPLEMENTATION.md) for setup instructions
3. Enable debug logging: `LOG_LEVEL=debug pnpm dev`
4. Check the server logs for error messages
## Architecture Overview
```
┌─────────────┐
│ Browser │
└──────┬──────┘
│ 1. Visit /slack/install
▼
┌─────────────────┐
│ MCP Server │
│ (This App) │
└────────┬────────┘
│ 2. Redirect to Slack
▼
┌─────────────────┐
│ Slack OAuth │
│ Authorization │
└────────┬────────┘
│ 3. User approves
▼
┌─────────────────┐
│ MCP Server │
│ /oauth/callback│
└────────┬────────┘
│ 4. Exchange code for token
│ 5. Store installation
▼
┌─────────────────┐
│ Success Page │
└─────────────────┘
Later:
┌─────────────┐
│ MCP Client │
└──────┬──────┘
│ Call tools with team_id
▼
┌─────────────────┐
│ MCP Server │
│ /mcp endpoint │
└────────┬────────┘
│ Use stored token
▼
┌─────────────────┐
│ Slack API │
└─────────────────┘
```
## Available Tools
- **slack_list_channels** - List all channels in workspace
- **slack_get_channel_history** - Read messages from a channel
- **slack_post_message** - Send a message to a channel
All tools require `team_id` parameter (the workspace ID from OAuth).
---
**You're all set!** 🎉
Your Slack MCP server is now running and ready to use.
