@chinchillaenterprises/mcp-slack/README.md

Multi-account MCP server for Slack with persistent credential storage and runtime workspace switching

# MCP Slack Server

A powerful multi-account Model Context Protocol (MCP) server for Slack that enables seamless workspace switching and persistent credential storage.

## Features

- 🔄 **Multi-Account Support**: Switch between multiple Slack workspaces at runtime
- 🔐 **Secure Credential Storage**: Uses native OS keychains with encrypted file-based fallback
- ⚡ **Fast Performance**: <200ms startup time for 10+ workspaces
- 🛡️ **Dual Storage System**: Automatic fallback to encrypted file storage if keychain unavailable
- 🔍 **Comprehensive Slack Tools**: 40+ tools for messages, channels, users, files, and more
- 📁 **Reliable Persistence**: Accounts persist across Claude sessions
- ✨ **Automatic Markdown Conversion**: Converts common markdown formatting to Slack's mrkdwn format

## Installation

### Using Claude Desktop

```bash
claude mcp add slack -- npx @chinchillaenterprises/mcp-slack
```

### Using Claude Code (Recommended)

```bash
# Install with user scope for persistence across sessions
claude mcp add slack -s user -- npx @chinchillaenterprises/mcp-slack

# Or with environment variables for default workspace
claude mcp add slack -s user -e DEFAULT_BOT_TOKEN=xoxb-YOUR-BOT-TOKEN -e DEFAULT_TEAM_ID=YOUR-TEAM-ID -- npx @chinchillaenterprises/mcp-slack
```

### Manual Installation

```bash
npm install -g @chinchillaenterprises/mcp-slack
```

## Configuration

### Environment Variables

For the default workspace:
- `DEFAULT_BOT_TOKEN`: Slack bot token (xoxb-...)
- `DEFAULT_USER_TOKEN`: Slack user token (xoxp-...)
- `DEFAULT_TEAM_ID`: Slack team/workspace ID
- `DEFAULT_ACCOUNT_NAME`: Display name for the workspace

## Usage

### Account Management

The V3 architecture introduces powerful account management capabilities:

- **list_accounts**: View all configured workspaces
- **switch_account**: Change active workspace at runtime
- **add_account**: Add new workspace credentials
- **remove_account**: Remove workspace from configuration
- **update_account**: Update existing workspace credentials

### Core Slack Tools

#### Messaging
- `slack_send_message`: Send messages to channels (with automatic markdown → Slack formatting)
- `slack_send_formatted_message`: Send rich Block Kit messages
- `slack_edit_message`: Edit existing messages
- `slack_delete_message`: Delete messages
- `slack_schedule_message`: Schedule messages for later
- `slack_forward_message`: Forward messages between channels

#### Channels & History
- `slack_list_channels`: List accessible channels
- `slack_get_channel_history`: Get recent messages
- `slack_get_thread_replies`: Get thread conversations

#### Search
- `slack_search_messages`: Search across workspace
- `slack_search_by_user`: Find messages from specific users
- `slack_search_by_date_range`: Search within date ranges
- `slack_search_files`: Search for shared files

#### Users & Teams
- `slack_list_users`: List workspace members
- `slack_get_user_by_name`: Find users by name
- `slack_get_user_info`: Get detailed user information
- `slack_get_user_status`: Check user status
- `slack_get_user_profile`: Get full profile details

#### Reactions & Pins
- `slack_add_reaction`: Add emoji reactions
- `slack_bulk_react_messages`: React to multiple messages
- `slack_pin_message`: Pin important messages
- `slack_unpin_message`: Unpin messages

#### Productivity
- `slack_create_reminder`: Set reminders
- `slack_list_reminders`: View active reminders
- `slack_get_workspace_stats`: Get workspace analytics

### Automatic Markdown Conversion

The `slack_send_message` tool now automatically converts common markdown formatting to Slack's mrkdwn format:

- **Bold**: `**text**` → `*text*`
- **Links**: `[text](url)` → `<url|text>`
- **Strikethrough**: `~~text~~` → `~text~`
- **Headers**: `# Header` → `*Header*`
- **Lists**: `- item` → `• item`

This means Claude can use standard markdown formatting and it will appear correctly in Slack without manual conversion.

## Advanced Features

### Persistent Storage

The server uses a dual-storage system for maximum reliability:

1. **Primary Storage**: Native OS keychain
   - **macOS**: Keychain Access
   - **Windows**: Credential Manager  
   - **Linux**: Secret Service API

2. **Fallback Storage**: Encrypted file storage
   - Location: `~/.mcp-slack/accounts.json`
   - Credentials encrypted using AES-256-CBC
   - Automatic failover if keychain unavailable
   - Permissions restricted to user only (0600)

### Data Security

- Bot tokens and user tokens are encrypted at rest
- Encryption key stored separately with restricted permissions
- No plaintext credentials on disk
- Automatic cleanup of stale sessions

### Performance Optimizations

- Lazy loading of workspace configurations
- Efficient caching of API responses
- Minimal startup overhead

## Architecture

MCP Slack Server implements the Account Manager Tools Pattern with dual storage:

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Claude    │────▶│ MCP Server   │────▶│   Slack     │
│   Desktop   │     │              │     │ Workspaces  │
└─────────────┘     └──────────────┘     └─────────────┘
                            │
                    ┌───────┴───────┐
                    ▼               ▼
            ┌──────────────┐ ┌──────────────┐
            │ OS Keychain  │ │  Encrypted   │
            │   Storage    │ │ File Storage │
            └──────────────┘ └──────────────┘
                Primary         Fallback
```

## Troubleshooting

### "Secure storage unavailable"
This warning appears when keychain access is denied or unavailable. The server will continue working with temporary storage.

### Missing channels or users
Ensure your bot token has the necessary OAuth scopes:
- `channels:read`
- `chat:write`
- `users:read`
- `files:read`

### Performance issues
- Check network connectivity to Slack
- Verify token permissions
- Review workspace size (very large workspaces may need pagination)

## Development

### Building from source

```bash
git clone https://github.com/ChinchillaEnterprises/ChillMCP.git
cd ChillMCP/mcp-slacker-v3
npm install
npm run build
```

### Contributing

Issues and pull requests are welcome at the [GitHub repository](https://github.com/ChinchillaEnterprises/ChillMCP).

## License

MIT License - see LICENSE file for details.

## Credits

Built by [Chinchilla Enterprises](https://github.com/ChinchillaEnterprises) for the MCP ecosystem.