# Slack MCP Server

A production-ready Model Context Protocol (MCP) server for Slack integration. This server enables AI assistants to interact with Slack workspaces through a secure, multi-tenant OAuth flow.

## Features

- 🔐 **Secure OAuth 2.0 Flow** - Full Slack OAuth v2 implementation with state validation
- 🏢 **Multi-Tenant Support** - Handle multiple Slack workspaces simultaneously
- 🔄 **Token Rotation** - Automatic token refresh for long-lived installations
- 🛡️ **Production Security** - CORS, API key protection, Helmet.js, request timeouts
- 📊 **Structured Logging** - Pino logger with configurable log levels
- 🐳 **Docker Ready** - Multi-stage Dockerfile with non-root user
- ⚡ **MCP Tools** - Post messages, read channel history, list channels

## Architecture

This server uses the **Streamable HTTP transport** for MCP, making it suitable for web-based AI assistants. It manages:

- **OAuth Flow**: `/slack/install` and `/slack/oauth/callback` endpoints
- **MCP Endpoint**: `/mcp` for all MCP protocol communication
- **Session Management**: Automatic session pruning with configurable TTL
- **Installation Storage**: Pluggable storage interface (in-memory by default)

## Prerequisites

1. **Slack App** - Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps)
2. **Node.js** - Version 18+ required
3. **pnpm** - Package manager (or npm/yarn)

## Quick Start

### 1. Install Dependencies

```bash
pnpm install
```

### 2. Configure Environment

Copy the example environment file and fill in your values:

```bash
cp .env.example .env
```

Required variables:
- `SLACK_CLIENT_ID` - From your Slack app's OAuth settings
- `SLACK_CLIENT_SECRET` - From your Slack app's OAuth settings
- `SLACK_REDIRECT_URI` - Your callback URL (e.g., `https://yourdomain.com/slack/oauth/callback`)
- `SLACK_SCOPES` - Comma-separated bot scopes (e.g., `chat:write,channels:history,channels:read`)
- `AFFINITYBOTS_MCP_API_KEY` - Secret key to protect your MCP endpoint

### 3. Run Development Server

```bash
pnpm dev
```

The server will start on `http://localhost:8080` by default.

### 4. Install Slack App

1. Navigate to `http://localhost:8080/slack/install`
2. Authorize the app for your workspace
3. You'll be redirected back with a success message

### 5. Use MCP Tools

Connect your MCP client to `http://localhost:8080/mcp` with:
- **Authorization header**: `Bearer YOUR_AFFINITYBOTS_MCP_API_KEY`
- **Origin header**: Must match `ALLOWED_ORIGINS` if configured

## Available MCP Tools

### `slack_post_message`
Post a message to a Slack channel.

**Parameters:**
- `team_id` (string) - Slack workspace/team ID (T...)
- `channel_id` (string) - Channel/DM ID (C... or D...)
- `text` (string) - Message text (1-4000 characters)
- `thread_ts` (string, optional) - Thread timestamp to reply to

### `slack_get_channel_history`
Read messages from a Slack channel.

**Parameters:**
- `team_id` (string) - Slack workspace/team ID
- `channel_id` (string) - Channel/DM ID
- `limit` (number, optional) - Number of messages (1-200, default: 50)

### `slack_list_channels`
List all channels in the workspace.

**Parameters:**
- `team_id` (string) - Slack workspace/team ID
- `types` (string, optional) - Channel types: `public_channel,private_channel,mpim,im` (default: `public_channel`)
- `limit` (number, optional) - Number of channels (1-1000, default: 200)

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `8080` | Server port |
| `HOST` | No | `0.0.0.0` | Server host |
| `PUBLIC_BASE_URL` | No | `http://localhost:8080` | Public URL for OAuth redirects |
| `SLACK_CLIENT_ID` | **Yes** | - | Slack app client ID |
| `SLACK_CLIENT_SECRET` | **Yes** | - | Slack app client secret |
| `SLACK_REDIRECT_URI` | **Yes** | - | OAuth callback URL |
| `SLACK_SCOPES` | **Yes** | - | Comma-separated bot scopes |
| `AFFINITYBOTS_MCP_API_KEY` | Recommended | - | API key for MCP endpoint |
| `ALLOWED_ORIGINS` | No | - | Comma-separated allowed origins for CORS |
| `SESSION_TTL_MS` | No | `900000` | MCP session timeout (15 min) |
| `LOG_LEVEL` | No | `info` | Log level: trace, debug, info, warn, error, fatal |

### Required Slack Scopes

At minimum, your Slack app needs these bot token scopes:
- `chat:write` - Post messages
- `channels:history` - Read public channel messages
- `channels:read` - List public channels

Additional recommended scopes:
- `groups:history` - Read private channel messages
- `groups:read` - List private channels
- `im:history` - Read direct messages
- `im:read` - List direct messages
- `mpim:history` - Read group DM messages
- `mpim:read` - List group DMs

## Production Deployment

### Using Docker

Build the image:

```bash
docker build -t slack-mcp-server .
```

Run the container:

```bash
docker run -d \
  -p 8080:8080 \
  -e SLACK_CLIENT_ID=your_client_id \
  -e SLACK_CLIENT_SECRET=your_client_secret \
  -e SLACK_REDIRECT_URI=https://yourdomain.com/slack/oauth/callback \
  -e SLACK_SCOPES=chat:write,channels:history,channels:read \
  -e AFFINITYBOTS_MCP_API_KEY=your_secret_key \
  -e ALLOWED_ORIGINS=https://yourdomain.com \
  slack-mcp-server
```

### Production Checklist

- [ ] Set `AFFINITYBOTS_MCP_API_KEY` to a strong random value
- [ ] Configure `ALLOWED_ORIGINS` with your frontend domains
- [ ] Use HTTPS for all endpoints (required by Slack)
- [ ] Set `PUBLIC_BASE_URL` to your public HTTPS URL
- [ ] Replace `InMemoryInstallStore` with persistent storage (Redis/PostgreSQL)
- [ ] Set up monitoring and alerting
- [ ] Configure log aggregation
- [ ] Set appropriate `SESSION_TTL_MS` for your use case
- [ ] Enable Slack token rotation in your app settings (recommended)
- [ ] Set up rate limiting at the reverse proxy level
- [ ] Configure health check monitoring on `/health`

## Storage

The default `InMemoryInstallStore` is suitable for development but **not for production**. For production, implement the `InstallStore` interface with a persistent backend:

```typescript
export interface InstallStore {
  upsert(install: SlackInstallation): Promise<void>;
  getByTeamId(teamId: string): Promise<SlackInstallation | null>;
}
```

Recommended storage options:
- **PostgreSQL** - Best for relational data and complex queries
- **Redis** - Fast, simple key-value storage
- **MongoDB** - Document-based storage
- **DynamoDB** - Serverless AWS option

## Security Features

### Implemented
- ✅ CSRF protection via OAuth state parameter
- ✅ API key authentication for MCP endpoint
- ✅ CORS with origin allowlist
- ✅ Helmet.js security headers
- ✅ Request timeouts (30s)
- ✅ Session expiration and pruning
- ✅ Automatic token refresh
- ✅ Secure error messages (no info leakage)
- ✅ Non-root Docker user

### Recommended Additional Security
- Add rate limiting (e.g., express-rate-limit)
- Use a reverse proxy (nginx, Caddy) with TLS
- Implement request size limits
- Add request ID tracking
- Set up WAF rules
- Enable Slack signing secret verification for webhooks (if added)

## Monitoring

### Health Check

```bash
curl http://localhost:8080/health
```

Returns `ok` if the server is running.

### Logs

The server uses structured JSON logging via Pino. Key log events:
- OAuth flow initiation and completion
- MCP session creation and expiration
- Token refresh operations
- API errors and warnings
- Security events (unauthorized access, invalid origins)

Set `LOG_LEVEL=debug` for detailed debugging.

## Troubleshooting

### OAuth Errors

**"Invalid or expired state"**
- The OAuth state token expired (10 min TTL)
- Try the installation flow again

**"Slack OAuth failed: invalid_code"**
- The authorization code was already used or expired
- Restart the installation flow

**"Origin not allowed"**
- Your frontend origin is not in `ALLOWED_ORIGINS`
- Add your origin to the environment variable

### MCP Errors

**"Unauthorized"**
- Missing or invalid `Authorization` header
- Ensure you're sending `Bearer YOUR_API_KEY`

**"Unknown or expired session"**
- MCP session expired (default 15 min)
- Reinitialize the MCP connection

**"No Slack installation found"**
- The workspace hasn't installed the app
- Complete the OAuth flow first

### Token Errors

**"Token refresh failed"**
- The refresh token is invalid or revoked
- User needs to reinstall the app
- Check if token rotation is enabled in Slack app settings

## Development

### Project Structure

```
slack-mcp-server/
├── src/
│   ├── index.ts          # Main server and routing
│   ├── mcp.ts            # MCP tool definitions
│   ├── slackOauth.ts     # OAuth flow handlers
│   ├── slackClient.ts    # Slack API client with token refresh
│   ├── installStore.ts   # Installation storage interface
│   └── security.ts       # Security utilities
├── Dockerfile
├── package.json
├── tsconfig.json
└── README.md
```

### Adding New Tools

Register new tools in `src/mcp.ts`:

```typescript
server.tool(
  "tool_name",
  "Tool description",
  {
    team_id: z.string(),
    // ... other parameters
  },
  async ({ team_id, ...params }) => {
    const slack = await getSlackClientForTeam(store, team_id);
    // ... implement tool logic
    return { content: [{ type: "text", text: "result" }] };
  }
);
```

### Testing

```bash
# Run development server with debug logging
LOG_LEVEL=debug pnpm dev

# Build for production
pnpm build

# Run production build
pnpm start
```

## License

MIT

## Support

For issues and questions:
1. Check the [IMPLEMENTATION.md](./IMPLEMENTATION.md) guide
2. Review Slack API documentation at [api.slack.com](https://api.slack.com)
3. Check MCP documentation at [modelcontextprotocol.io](https://modelcontextprotocol.io)

## Contributing

Contributions welcome! Please:
1. Follow the existing code style
2. Add tests for new features
3. Update documentation
4. Ensure all lints pass