# Slack Channel MCP Server

An MCP (Model Context Protocol) server that enables Slackbot to create Slack channels through natural language conversation.

## Overview

This server exposes a single tool `create_slack_channel` that allows you to create Slack channels by talking to Slackbot. It uses the Slack API's [conversations.create](https://docs.slack.dev/reference/methods/conversations.create/) method.

**Architecture:**
```
User → Slackbot (Slack's AI) → MCP Server (HTTP) → Slack API
```

## Quick Start

### 1. Prerequisites

- **Node.js 18+** - For running the server
- **npm** - For dependency management
- **ngrok** - For exposing localhost to the internet (for local development)
- **Slack workspace** - Where you want to create channels
- **Slack app credentials** - Bot token with appropriate scopes

### 2. Install Dependencies

```bash
cd /Users/asalinerojeffrey/Projects/slack-channel-mcp-server
npm install
```

### 3. Get Your Slack Bot Token

1. Go to https://api.slack.com/apps
2. Click **"Create New App"** → **"From scratch"**
3. **App name:** `Channel Creator MCP`
4. **Select your workspace**
5. Go to **"OAuth & Permissions"** in the left sidebar
6. Under **"Scopes"**, add these **Bot Token Scopes:**
   - `mcp:connect` (required for MCP)
   - `channels:manage` (to create public channels)
   - `groups:write` (to create private channels)
7. Click **"Install to Workspace"** at the top
8. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
9. Save it to your `.env` file

### 4. Configure Environment

```bash
# Copy the example file
cp .env.example .env

# Edit .env and add your bot token
# SLACK_BOT_TOKEN=xoxb-your-token-here
```

### 5. Start the Server Locally

```bash
npm run dev
```

You should see:
```
🚀 Slack Channel MCP Server running on http://localhost:3000
   MCP endpoint: http://localhost:3000/mcp
   Health check: http://localhost:3000/health
```

### 6. Expose with ngrok (New Terminal)

```bash
# Install ngrok if needed
brew install ngrok

# Start ngrok
ngrok http 3000
```

You'll see something like:
```
Forwarding                    https://1a2b3c4d.ngrok.io -> http://localhost:3000
```

**Copy the HTTPS URL** (e.g., `https://1a2b3c4d.ngrok.io`) - you'll need this next.

### 7. Configure Slack App for MCP

1. Go back to https://api.slack.com/apps → Your app
2. In the left sidebar under **"Features"**, click **"MCP Servers"**
3. Click **"Add MCP Server"**
4. Fill in:
   - **Display name:** `Channel Creator`
   - **HTTPS endpoint URL:** Paste your ngrok URL + `/mcp` (e.g., `https://1a2b3c4d.ngrok.io/mcp`)
   - **Authentication method:** `No Auth` (for demo)
5. Click **"Save"**
6. Server should show as **"Connected"** ✅

### 8. Test with Slackbot

1. Open your Slack workspace
2. Find **Slackbot** in Direct Messages or @mention it in a channel
3. Try asking:
   - "Create a channel called test-demo"
   - "Make a private channel for our team"
   - "Set up a new channel named project-alpha"

4. Slackbot will:
   - Recognize your intent
   - Offer the `create_slack_channel` tool
   - Ask you to authorize it (first time only)
   - Execute the tool and confirm

## Testing Before Slackbot

### Test with MCP Inspector

The MCP Inspector is a UI tool to test MCP servers locally:

```bash
# Terminal 3: Start MCP Inspector
npx @modelcontextprotocol/inspector
```

1. Select **"Streamable HTTP"** from the dropdown
2. Enter the URL: `http://localhost:3000/mcp`
3. Click **"Connect"**
4. You'll see the `create_slack_channel` tool
5. Test it by entering:
   - **name:** `mcp-test-123`
   - **is_private:** `false`
6. Click **"Call Tool"**
7. Check your Slack workspace - the channel should appear!

### Test with curl

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

Should return JSON with tool definitions.

### Test the tool directly

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_slack_channel",
      "arguments": {
        "name": "curl-test-channel",
        "is_private": false
      }
    }
  }'
```

## Tool Reference

### `create_slack_channel`

Creates a new Slack channel.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | ✅ Yes | Channel name (1-80 chars, lowercase, no spaces, alphanumeric + `-` + `_`) |
| `is_private` | boolean | ❌ No | Create as private channel (default: `false` = public) |
| `description` | string | ❌ No | Channel topic/description |

**Example:**

```json
{
  "name": "project-alpha",
  "is_private": false,
  "description": "Planning and development for Project Alpha"
}
```

**Response on Success:**

```json
{
  "success": true,
  "message": "Channel created successfully",
  "channel": {
    "id": "C12345678",
    "name": "project-alpha",
    "is_private": false,
    "created": 1704067200,
    "url": "https://slack.com/app_redirect?channel=C12345678"
  }
}
```

**Response on Error:**

```json
{
  "success": false,
  "error": "Channel name \"my-channel\" is already taken. Please choose a different name."
}
```

## Common Errors & Solutions

### "Unexpected error" in Slack

1. **Check if ngrok is running:** 
   ```bash
   curl https://<your-ngrok-url>/health
   ```
2. **Verify server is accessible:**
   ```bash
   curl https://<your-ngrok-url>/mcp -X POST
   ```
3. **Check Slack app MCP configuration has correct URL** (with `/mcp` at the end)

### Tool doesn't appear in Slackbot

1. Verify MCP server is **"Connected"** in Slack app settings
2. Test with MCP Inspector: Is the tool listed?
3. Restart Slack client
4. Try a fresh conversation with Slackbot

### "name_taken" error

Channel name already exists. Try a different name or check existing channels in Slack.

### "missing_scope" error

Your Slack app is missing required permissions:
1. Go to OAuth & Permissions in your Slack app
2. Verify you have these scopes:
   - `mcp:connect`
   - `channels:manage`
   - `groups:write`
3. If missing, add them and reinstall the app to your workspace

### "not_authed" error

Bot token is invalid or expired:
1. Generate a new token at https://api.slack.com/apps → Your app → OAuth & Permissions
2. Update `.env` with the new token
3. Restart the server

### 60 second timeout

Tool took too long to respond. This could be:
- Network latency to Slack API
- Slack API rate limiting
- Invalid token causing retry logic

Try again or check your Slack app's token permissions.

## Troubleshooting

### Server won't start

```bash
# Check if port 3000 is in use
lsof -i :3000

# Use a different port
PORT=3001 npm run dev
```

### ngrok URL expires

Free ngrok URLs change every time you restart ngrok:
1. Get the new URL
2. Update Slack app MCP server configuration
3. No need to restart anything else

**For permanent URLs:** Upgrade to paid ngrok or deploy to a cloud provider.

### Bot missing permissions

**Solution:** Reinstall the app after adding scopes:
1. Go to https://api.slack.com/apps → Your app
2. Click "Install to Workspace"
3. Re-authorize the app
4. Copy the new token to `.env`
5. Restart server

## Production Deployment

To deploy beyond local testing, see **Deployment Options** in the plan file.

### Option 1: Render (Recommended for simplicity)

1. Push code to GitHub
2. Connect to Render.com
3. Create new Web Service
4. Set environment variable `SLACK_BOT_TOKEN`
5. Deploy
6. Use Render URL (https://...) in Slack app MCP configuration

### Option 2: Railway

Similar to Render, supports Node.js deployments with free tier.

### Option 3: Fly.io

Offers generous free tier and quick deployment.

### Option 4: Cloudflare Workers

For serverless deployment with minimal cost.

## Security Notes

⚠️ **For demo/development only:**
- Using "No Auth" authentication mode
- Bot token in environment variable

🔒 **For production:**
- Implement request signature verification
- Use "Slack Identity" authentication to receive user context
- Verify `_meta.slack` request signature before trusting
- Add request logging and monitoring
- Rate limit tool calls
- Deploy on HTTPS only

## Development

### Build for production

```bash
npm run build
npm start
```

### Project structure

```
src/
├── server.ts          # Main MCP server implementation
package.json           # Dependencies
tsconfig.json          # TypeScript config
.env.example           # Environment template
README.md              # This file
```

## API Reference

See the [Slack conversations.create API documentation](https://docs.slack.dev/reference/methods/conversations.create/)

## MCP Specification

Learn more about the Model Context Protocol:
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Servers](https://modelcontextprotocol.io/implementations#mcp-servers)

## Support

For issues:
1. Check this README's troubleshooting section
2. Test with MCP Inspector
3. Verify your Slack app token and scopes
4. Check server logs for error details

## License

MIT