# 🚀 Slack Notifications MCP Server

A powerful **Model Context Protocol (MCP)** server that brings Slack notifications to Claude AI workflows. Perfect for getting notified when long-running tasks complete, errors occur, or when user input is needed.

![Slack Notification Example](https://img.shields.io/badge/Slack-Notifications-green?style=for-the-badge&logo=slack)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)

## ✨ Features

- 📱 **Rich Slack Messages**: Formatted messages with attachments, colors, and fields
- 🎯 **Task Completion Notifications**: Specialized notifications for development workflows
- 🔧 **Webhook Configuration**: Easy setup with Slack webhook URLs
- 🌈 **Color-Coded Status**: Visual indicators for success, error, warning, and info
- 🎨 **Customizable**: Channel selection, bot username, emojis, and priority levels
- 🚀 **Zero Config**: Works with environment variables or runtime configuration

## 🛠️ Tools

### `send_slack_notification`
Send a customizable Slack notification with full formatting options.

**Parameters:**
- `title` (required): The notification title
- `message` (required): The notification message  
- `webhook_url` (optional): Slack webhook URL (if not configured globally)
- `channel` (optional): Target channel (e.g., #general, @username)
- `username` (optional): Bot username (default: "Claude Code")
- `icon_emoji` (optional): Bot emoji (default: ":robot_face:")
- `color` (optional): Message color (good, warning, danger, info, or hex)
- `priority` (optional): Priority level (low, normal, high, urgent)

### `slack_task_completion_notification`
Send a specialized notification for task completion with intelligent formatting.

**Parameters:**
- `status` (required): `success`, `error`, `warning`, or `info`
- `taskType` (optional): Type of task (e.g., "Build", "Deploy", "Test")
- `duration` (optional): How long the task took
- `summary` (optional): Brief summary of accomplishment
- `url` (optional): Related URL (e.g., localhost development server)
- `webhook_url` (optional): Slack webhook URL (if not configured globally)
- `channel` (optional): Target channel

### `configure_slack_webhook`
Configure global Slack webhook settings for the session.

**Parameters:**
- `webhook_url` (required): Your Slack webhook URL
- `default_channel` (optional): Default channel for notifications

## 🚀 Quick Start

### 1. Create Slack Webhook

1. **Go to Slack API**: Visit [api.slack.com](https://api.slack.com/apps)
2. **Create New App**: Click "Create New App" > "From scratch"
3. **Configure Incoming Webhooks**:
   - Go to "Incoming Webhooks" in the sidebar
   - Activate incoming webhooks
   - Click "Add New Webhook to Workspace"
   - Choose your channel and authorize
   - Copy the webhook URL (starts with `https://hooks.slack.com/services/...`)

### 2. Installation

1. **Clone this repository:**
   \`\`\`bash
   git clone https://github.com/chiuchau-cyril/mcp-slack-notifications.git
   cd mcp-slack-notifications
   \`\`\`

2. **Install dependencies:**
   \`\`\`bash
   npm install
   \`\`\`

3. **Build the project:**
   \`\`\`bash
   npm run build
   \`\`\`

### 3. Configuration

#### For Claude Code
Add to your Claude Code MCP configuration:

\`\`\`json
{
  "mcpServers": {
    "slack-notifications": {
      "command": "node",
      "args": ["/Users/cyril/Documents/git/mcp-servers/slack-notifications/dist/index.js"],
      "env": {
        "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
      }
    }
  }
}
\`\`\`

#### For Claude App  
Add to your Claude App MCP settings:

\`\`\`json
{
  "slack-notifications": {
    "command": "node",
    "args": ["/Users/cyril/Documents/git/mcp-servers/slack-notifications/dist/index.js"],
    "env": {
      "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
    }
  }
}
\`\`\`

### 4. Testing

Run the test suite to verify everything works:

\`\`\`bash
node test-slack-notifications.js
\`\`\`

## 📱 Usage Examples

### Basic Notification
\`\`\`javascript
// Simple notification
{
  "title": "🎉 Task Complete",
  "message": "Your build finished successfully!",
  "channel": "#development",
  "color": "good"
}
\`\`\`

### Development Workflow
\`\`\`javascript
// Task completion with details
{
  "status": "success",
  "taskType": "React Build",
  "duration": "2 minutes",
  "summary": "Compiled 45 components successfully",
  "url": "http://localhost:3000",
  "channel": "#dev-notifications"
}
\`\`\`

### Error Notification
\`\`\`javascript
// Error with high priority
{
  "title": "❌ Build Failed",
  "message": "TypeScript compilation errors detected",
  "color": "danger",
  "priority": "urgent",
  "channel": "#alerts"
}
\`\`\`

### Configuration
\`\`\`javascript
// Set up webhook for the session
{
  "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "default_channel": "#claude-notifications"
}
\`\`\`

## 🎯 Smart Notification Logic

This MCP server implements the same intelligent notification timing as the macOS version:

### ⚠️ **Immediate Notifications** (User Action Required)
- Commands waiting for confirmation (`Do you want to proceed?`)
- Password prompts
- Any user input required
- **Priority**: `urgent` with red color

### ✅ **Completion Notifications** (Task Finished)  
- Build processes completed
- Tests finished running
- Deployments completed
- **Color**: Green (success) / Red (error) / Orange (warning)

### 🔇 **No Notifications**
- Simple queries (`ls`, `pwd`)
- Commands still running normally
- Quick operations (< 30 seconds)

## 🎨 Slack Message Features

### Color Coding
- **Green** (`good`): Success, completed tasks
- **Orange** (`warning`): Warnings, partial failures
- **Red** (`danger`): Errors, critical issues
- **Blue** (`info`): Information, status updates
- **Custom**: Any hex color code (e.g., `#FF5733`)

### Priority Levels
- **Low**: `#cccccc` (gray)
- **Normal**: `#0099cc` (blue) 
- **High**: `#ff9500` (orange)
- **Urgent**: `#ff0000` (red)

### Rich Formatting
- **Attachments**: Structured message layout
- **Fields**: Key-value pairs with short/long display
- **Timestamps**: Automatic message timing
- **Footer**: "Claude Code" branding

## 🛡️ Requirements

- **Node.js 18+**
- **Slack workspace** with webhook permissions
- **Internet connection** for webhook delivery

## 🧪 Environment Variables

Set these for easier configuration:

\`\`\`bash
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
export SLACK_DEFAULT_CHANNEL="#claude-notifications"
\`\`\`

## 📖 Claude Rules Integration

For automatic notification behavior, add these rules to your Claude configuration:

\`\`\`markdown
# Automatically notify on task completion via Slack
When a task takes longer than 2 minutes or requires user input, 
send a Slack notification using the appropriate tool.

# Notification timing:
- User input needed → Immediate notification with urgent priority
- Task completed → Result notification with appropriate status
- Errors occurred → Error notification with danger color
\`\`\`

## 🔒 Security Notes

- **Webhook URLs contain secrets** - keep them private
- **Don't commit webhook URLs** to version control
- **Use environment variables** for production deployments
- **Limit webhook permissions** to necessary channels only

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙋‍♂️ Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/chiuchau-cyril/mcp-slack-notifications/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/chiuchau-cyril/mcp-slack-notifications/discussions)
- 📧 **Email**: Contact for enterprise support

## 🔗 Related Projects

- [macOS Notifications MCP Server](https://github.com/chiuchau-cyril/mcp-macos-notifications) - Native macOS notifications
- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP documentation

---

**Made with ❤️ for the Claude AI ecosystem**