# Slack MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Slack workspaces through the Slack Web API.

## Features

### Channel Management
- **list_channels** - List all channels in the workspace
- **get_channel_info** - Get detailed information about a specific channel
- **create_channel** - Create a new channel
- **archive_channel** - Archive a channel
- **unarchive_channel** - Unarchive a channel
- **set_channel_topic** - Set channel topic
- **set_channel_purpose** - Set channel purpose

### User Management
- **list_users** - List all users in the workspace
- **get_user_info** - Get detailed information about a specific user
- **invite_to_channel** - Invite users to a channel

### Messaging
- **send_message** - Send a message to a channel (supports Block Kit)
- **update_message** - Update an existing message (supports Block Kit)
- **delete_message** - Delete a message
- **get_channel_history** - Get message history for a channel
- **search_messages** - Search for messages across the workspace

### Rich Message Formatting (Block Kit)
- **send_formatted_message** - Send formatted messages with headers, sections, fields
- **send_notification_message** - Send status notifications with emoji indicators
- **send_list_message** - Send formatted lists with titles and descriptions

### File Management
- **upload_file** - Upload a file to one or more channels

### Reactions
- **add_reaction** - Add a reaction to a message
- **remove_reaction** - Remove a reaction from a message

### Workspace
- **get_team_info** - Get information about the Slack workspace/team

## Installation

### Using pip (Recommended - Global Install)

For use with Claude Desktop or Claude CLI, install globally:

```bash
pip install slack-mcp-server
```

### From source

```bash
git clone <repository-url>
cd slack-mcp-server
pip install -e .
```

## Configuration

### Secure Credential Storage (Recommended)

The Slack MCP Server uses macOS Keychain for secure credential storage. This is much safer than storing tokens in files.

#### Quick Setup

```bash
# Run the interactive setup
slack-mcp-setup
# or
python -m slack_mcp.setup
```

The setup wizard will:
1. Guide you through obtaining a Slack API token
2. Securely store credentials in your macOS Keychain
3. Validate your configuration

#### Manual Keychain Setup

```python
from slack_mcp.credentials import CredentialManager

manager = CredentialManager()
manager.store_credential("api_token", "xoxb-your-slack-bot-token")
manager.store_credential("workspace_id", "T1234567890")  # Optional
```

### Environment Variables (Fallback)

If you prefer environment variables or are not on macOS, create a `.env` file:

```bash
# Required
SLACK_API_TOKEN=xoxb-your-slack-bot-token

# Optional
SLACK_WORKSPACE_ID=your-workspace-id
```

**⚠️ Security Warning**: Environment variables and `.env` files are less secure than keychain storage.

### Getting a Slack API Token

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Create a new app or select an existing one
3. Navigate to "OAuth & Permissions"
4. Add the required OAuth scopes (see below)
5. Install the app to your workspace
6. Copy the "Bot User OAuth Token" (starts with `xoxb-`)

### Required OAuth Scopes

The following OAuth scopes are required for full functionality:

**Core Scopes:**
- `channels:read` - View basic channel information
- `channels:manage` - Create and manage public channels
- `groups:read` - View private channel information
- `groups:write` - Create and manage private channels
- `chat:write` - Send messages
- `files:write` - Upload files
- `im:read` - View direct message channels
- `mpim:read` - View group direct message channels
- `reactions:read` - View reactions
- `reactions:write` - Add and remove reactions
- `team:read` - View team information
- `users:read` - View user information

**⚠️ Search Limitation:**
The `search_messages` tool uses Slack's search API which requires user tokens with the `search:read` scope. Since this server is designed for bot tokens (`xoxb-`), search functionality will not work. Consider removing this feature or switching to user token authentication if search is needed.

## Usage with Claude CLI (Recommended)

After installing globally, add the server using Claude CLI. First, find your slack-mcp-server installation path:

```bash
# Find your slack-mcp-server executable path
which slack-mcp-server
```

Then add it with Claude CLI:

```bash
claude mcp add slack /path/to/slack-mcp-server
```

For example:
```bash
claude mcp add slack /usr/local/bin/slack-mcp-server
```

This automatically configures the server in your Claude Desktop configuration.

## Usage with Claude Desktop (Manual Configuration)

Alternatively, you can manually add this to your `claude_desktop_config.json`:

#### With Keychain Storage (Recommended)

```json
{
  "mcpServers": {
    "slack": {
      "command": "python",
      "args": ["-m", "slack_mcp"]
    }
  }
}
```

#### With Environment Variables

```json
{
  "mcpServers": {
    "slack": {
      "command": "python",
      "args": ["-m", "slack_mcp"],
      "env": {
        "SLACK_API_TOKEN": "xoxb-your-slack-bot-token"
      }
    }
  }
}
```

## Usage with MCP Client

```python
from mcp import Client

# Initialize client
client = Client()

# Connect to the Slack MCP server
await client.connect("python", ["-m", "slack_mcp"])

# List available tools
tools = await client.list_tools()

# Use a tool
result = await client.call_tool("list_channels", {
    "types": "public_channel",
    "exclude_archived": True,
    "limit": 10
})
```

## Development

### Setting up the development environment

```bash
# Clone the repository
git clone <repository-url>
cd slack-mcp-server

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Set up credentials securely
slack-mcp-setup
```

### Running tests

```bash
pytest
```

### Code formatting

```bash
# Format with black
black slack_mcp/

# Lint with ruff
ruff check slack_mcp/
```

## Examples

### List public channels

```python
result = await client.call_tool("list_channels", {
    "types": "public_channel",
    "exclude_archived": True,
    "limit": 20
})
```

### Send a message

```python
result = await client.call_tool("send_message", {
    "channel": "C1234567890",  # Channel ID
    "text": "Hello from MCP!"
})
```

### Search for messages

```python
result = await client.call_tool("search_messages", {
    "query": "project deadline",
    "sort": "timestamp",
    "sort_dir": "desc",
    "count": 10
})
```

### Upload a file

```python
result = await client.call_tool("upload_file", {
    "channels": "C1234567890,C0987654321",  # Comma-separated channel IDs
    "content": "This is the file content",
    "filename": "report.txt",
    "title": "Weekly Report",
    "initial_comment": "Here's this week's report"
})
```

### Send a formatted message with Block Kit

```python
result = await client.call_tool("send_formatted_message", {
    "channel": "C1234567890",
    "title": "Project Update",
    "text": "Here's the latest update on our project progress",
    "fields": "Status: In Progress, Due Date: Next Friday, Assignee: @john",
    "context": "Last updated 2 hours ago"
})
```

### Send a notification message

```python
result = await client.call_tool("send_notification_message", {
    "channel": "C1234567890",
    "status": "success",
    "title": "Deployment Complete",
    "description": "The application has been successfully deployed to production",
    "details": "Build #123 deployed at 14:30 UTC"
})
```

### Send a list message

```python
result = await client.call_tool("send_list_message", {
    "channel": "C1234567890",
    "title": "Meeting Agenda",
    "description": "Items to discuss in today's standup",
    "items": "Sprint review\nBlocker discussion\nNext week planning\nDemo preparation"
})
```

### Send message with custom Block Kit

```python
result = await client.call_tool("send_message", {
    "channel": "C1234567890",
    "text": "Custom formatted message",
    "blocks": json.dumps([
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "*Important Notice*\nThis is a custom Block Kit message"
            }
        },
        {"type": "divider"},
        {
            "type": "context",
            "elements": [
                {
                    "type": "mrkdwn",
                    "text": "Created with custom blocks"
                }
            ]
        }
    ])
})
```

## Error Handling

The server returns JSON-formatted error messages when operations fail:

```json
{
  "error": "Slack API error: channel_not_found"
}
```

Common error codes:
- `not_authed` - Invalid or missing API token
- `channel_not_found` - Channel doesn't exist
- `user_not_found` - User doesn't exist
- `message_not_found` - Message doesn't exist
- `no_permission` - Bot lacks required permissions
- `rate_limited` - API rate limit exceeded

## Security Considerations

- **🔐 Keychain Storage**: Use macOS Keychain for secure credential storage (recommended)
- **API Token**: Never commit your Slack API token to version control
- **Permissions**: Only grant the minimum required OAuth scopes
- **Rate Limits**: The server respects Slack's rate limits (see [Slack Rate Limits](https://api.slack.com/docs/rate-limits))
- **Message Content**: Be mindful of sensitive information in messages and files

### Credential Management Commands

```bash
# Interactive setup wizard
slack-mcp-setup

# View stored credentials
python -c "from slack_mcp.credentials import CredentialManager; m = CredentialManager(); print(m.list_stored_credentials())"

# Delete specific credential
python -c "from slack_mcp.credentials import CredentialManager; CredentialManager().delete_credential('api_token')"
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Support

For issues and questions, please create an issue in the repository.