https://github.com/karbassi/slack-mcp
MCP server exposing 193 Slack Web API methods as tools for AI agents
https://github.com/karbassi/slack-mcp
ai-agents fastmcp mcp mcp-server model-context-protocol slack slack-api
Last synced: 3 months ago
JSON representation
MCP server exposing 193 Slack Web API methods as tools for AI agents
- Host: GitHub
- URL: https://github.com/karbassi/slack-mcp
- Owner: karbassi
- License: mit
- Created: 2026-02-07T12:58:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-22T14:56:10.000Z (3 months ago)
- Last Synced: 2026-03-22T18:55:36.928Z (3 months ago)
- Topics: ai-agents, fastmcp, mcp, mcp-server, model-context-protocol, slack, slack-api
- Language: Python
- Homepage: https://github.com/karbassi/slack-mcp#readme
- Size: 438 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Slack MCP
**Your entire Slack workspace — available to any AI.**
[](https://pypi.org/project/slack-mcp/)
[](LICENSE)
A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives LLMs full access to [Slack](https://slack.com).
Messages, channels, files, canvases, lists, search, reactions — all of it.
**220 tools** · **36 API families** · **Every Slack feature**
---
## Quick Start
### 1. Create a Slack App
1. Go to [api.slack.com/apps](https://api.slack.com/apps) > **Create New App** > **From a manifest**
2. Paste the contents of [`manifest.json`](manifest.json)
3. Install to your workspace
4. Copy the **User OAuth Token** (`xoxp-...`) from **OAuth & Permissions**
### 2. Add to your AI client
Claude Code
```bash
claude mcp add slack -- uvx --from git+https://github.com/karbassi/slack-mcp.git slack-mcp
```
Then set `SLACK_XOXP_TOKEN` in your shell environment.
Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"slack": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
"env": {
"SLACK_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
Cursor
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"slack": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
"env": {
"SLACK_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"slack": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
"env": {
"SLACK_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
VS Code / GitHub Copilot
Add to your VS Code `settings.json`:
```json
{
"mcp": {
"servers": {
"slack": {
"command": "uvx",
"args": ["--from", "git+https://github.com/karbassi/slack-mcp.git", "slack-mcp"],
"env": {
"SLACK_XOXP_TOKEN": "xoxp-..."
}
}
}
}
}
```
Local clone
```json
{
"mcpServers": {
"slack": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/slack-mcp", "slack-mcp"]
}
}
}
```
## What Can It Do?
> *"Catch me up on #engineering from today"*
> *"Reply to Sarah's thread saying we'll ship it Monday"*
> *"Search for anything about the Q3 roadmap"*
> *"Create a channel called #project-atlas and invite the design team"*
| Domain | Tools | Highlights |
|---|---|---|
| **Conversations** | 28 | History, threads, replies, create, archive, invite, mark read |
| **Undocumented** | 28 | Drafts, saved items, emoji management, granular search, sidebar, threads |
| **Files** | 16 | Upload, share, edit, list, remote files |
| **Chat** | 14 | Send, reply, schedule, update, delete, ephemeral |
| **Users** | 12 | Profile, presence, lookup, list |
| **Lists** | 12 | Create, edit items, manage access |
| **Legacy** | 11 | Slash commands, file editing, bot listing |
| **Team** | 9 | Info, preferences, access logs, billing |
| **Apps** | 8 | Manifests, connections, authorizations |
| **Usergroups** | 7 | Create, update, manage members |
| **Workflows** | 7 | Featured workflows, step completion |
| **Canvases** | 6 | Create, edit, sections, access control |
| **Calls** | 6 | Start, end, manage participants |
| **+ 23 more** | | DND, reminders, bookmarks, reactions, pins, stars, views, search, auth, bots, emoji, ... |
Plus `resolve_names` (bulk ID→name resolution) and `cache_clear` (bust the response cache on demand) utility tools.
### Beyond the Official API
39 undocumented and legacy endpoints — the same internal APIs that Slack's own apps use. Requires session tokens (`xoxc`+`xoxd`).
Session endpoints — workspace state the official API doesn't expose
| Endpoint | What it provides |
|---|---|
| `client.boot` | Full workspace bootstrap — channels, users, prefs, feature flags |
| `client.counts` | Unread counts per channel/DM/thread plus mention counts |
| `client.userBoot` | User-specific bootstrap data scoped to the authenticated user |
| `threads.getView` | Thread inbox — the list of threads with read/unread state |
| `subscriptions.thread.mark` | Mark individual threads as read or unread |
| `drafts.list` | List all unsent message drafts |
| `drafts.create` | Create a message draft with Block Kit text |
| `drafts.update` | Edit an existing draft |
| `drafts.delete` | Delete a draft |
| `saved.list` | List saved-for-later items |
| `saved.add` | Save a message for later with optional due date |
| `saved.delete` | Remove a saved-for-later item |
| `emoji.add` | Add a custom emoji from a URL |
| `emoji.remove` | Remove a custom emoji |
| `emoji.adminList` | Emoji with rich metadata — uploader, date, usage stats |
| `search.modules.messages` | Granular message search |
| `search.modules.files` | File-specific search |
| `search.modules.channels` | Server-side channel search by name or topic |
| `search.modules.people` | Fuzzy people search by name, title, department |
| `search.modules.dms` | Search within DMs only |
| `conversations.view` | Channel view with read state and personal config |
| `conversations.listPrefs` | Per-channel notification and mute preferences |
| `users.channelSections.list` | Sidebar organization — custom sections, favorites |
| `users.priority.list` | Contacts ranked by interaction frequency |
| `experiments.getByUser` | A/B test experiment assignments |
| `api.features` | Workspace feature flags |
| `aiApps.list` | AI applications configured in the workspace |
Legacy endpoints — functionality missing from the official API
| Endpoint | What it provides |
|---|---|
| `chat.command` | Execute slash commands programmatically |
| `commands.list` | List all slash commands including custom ones |
| `files.edit` | Edit a file's title, content, or filetype in-place |
| `files.share` | Share a file to a channel |
| `bots.list` | List all bot users in the workspace |
| `team.prefs.get` | Team-level preferences — retention, permissions, domains |
| `users.prefs.get` | All user preferences — notifications, sidebar, theme |
| `users.prefs.set` | Set any individual user preference |
| `users.admin.invite` | Invite users by email (Enterprise Grid) |
| `users.admin.setInactive` | Deactivate a user account (Enterprise Grid) |
| `channels.delete` | Dead method — included for completeness |
> [!WARNING]
> Undocumented endpoints can break without notice. They use session tokens (`xoxc`+`xoxd`) which expire and must be re-grabbed from browser cookies.
## Authentication
| Variable | Required | Description |
|---|---|---|
| `SLACK_XOXP_TOKEN` | **Yes** | User OAuth token from your Slack app |
| `SLACK_XOXC_TOKEN` | No | Browser session token for undocumented endpoints |
| `SLACK_XOXD_TOKEN` | No | Browser session cookie (paired with `xoxc`) |
> [!TIP]
> The `xoxp` token covers all Slack Web API tools. Utility tools like `resolve_names` and `cache_clear` work without additional auth. For undocumented endpoints (unread counts, workspace boot, file editing), you also need `xoxc`+`xoxd` — grab them from your browser cookies while logged into slack.com.
## Caching
Responses are cached automatically to reduce API calls:
- **Stable data** (users, teams, bots, emoji) — 1 hour TTL
- **Dynamic data** (channel lists, members, bookmarks) — 5 minute TTL
- **Old threads** (`conversations_replies` with ts > 1 hour old) — 1 hour TTL
- **Bounded history** (`conversations_history` with old date range) — 1 hour TTL
- **Resolved names** (user/bot → 1 hour, channel → 5 minutes)
Cache is stored at the platform-native location (`~/Library/Caches/slack-mcp` on macOS, `~/.cache/slack-mcp` on Linux). Set `XDG_CACHE_HOME` to override.
Use the `cache_clear` tool to bust the cache when you need fresh data.
### Name Resolution
All tool responses automatically resolve user, channel, DM, and bot IDs to display names via a `_resolved_names` field — no extra tool calls needed. Resolved names are disk-cached to avoid redundant API lookups.
## Development
```bash
git clone https://github.com/karbassi/slack-mcp.git
cd slack-mcp
uv sync
uv run ruff check .
uv run pytest tests/
uv run pytest tests/ -m integration # requires tokens in .env
```
> [!NOTE]
> ~68 integration tests are skipped because they require a bot token (`xoxb`), Slack Connect, interactive triggers (e.g. `views.open`), or would be destructive (e.g. `auth.revoke`). Adding bot token support is a future goal.
## License
[MIT](LICENSE)