@jtalk22/slack-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# Slack MCP Server
+
+[![CI](https://github.com/jtalk22/slack-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/jtalk22/slack-mcp-server/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/jtalk22/slack-mcp-server/pulls)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/jtalk22?style=social)](https://github.com/sponsors/jtalk22)
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives Claude full access to your Slack workspace - including **DMs**, channels, and message history.
+
+<p align="center">
+  <img src="docs/images/demo-main.png" alt="Slack MCP Server Web UI" width="800">
+</p>
+
+> **[Try the Interactive Demo](https://jtalk22.github.io/slack-mcp-server/public/demo.html)** - See the Web UI in action with mock data
+
+## Why This Exists
+
+Official Slack integrations require OAuth and can't access DMs without explicit per-conversation authorization. This server uses your browser session tokens to provide the same access you have in Slack's web interface.
+
+**Works with:**
+- Claude Desktop (macOS/Windows)
+- Claude Code (CLI)
+- claude.ai (via Web UI)
+
+## Features
+
+- **Read Messages** - Fetch history from any DM or channel
+- **Full Export** - Export conversations with threads and resolved usernames
+- **Search** - Search messages across your workspace
+- **Send Messages** - Send to DMs or channels
+- **Auto Token Recovery** - Refreshes expired tokens from Chrome automatically
+- **Rate Limit Handling** - Automatic retry with exponential backoff
+- **Web UI** - Browser interface for use with claude.ai
+
+## Quick Start
+
+### 1. Install
+
+```bash
+# Clone the repository
+git clone https://github.com/jtalk22/slack-mcp-server.git
+cd slack-mcp-server
+
+# Install dependencies
+npm install
+```
+
+```
+
+### 2. Get Your Slack Tokens
+
+You need two tokens from your browser session:
+
+**Option A: Automatic (Recommended)**
+```bash
+# Open Chrome with Slack (app.slack.com) logged in
+npm run tokens:auto
+```
+
+**Option B: Manual**
+
+1. Open https://app.slack.com in Chrome
+2. Press F12 → Application → Cookies → Find `d` cookie (starts with `xoxd-`)
+3. Press F12 → Console → Run:
+   ```javascript
+   JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
+   ```
+4. Copy both values and run:
+   ```bash
+   npm run tokens:refresh
+   ```
+
+### 3. Configure Claude
+
+#### For Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "node",
+      "args": ["/path/to/slack-mcp-server/src/server.js"],
+      "env": {
+        "SLACK_TOKEN": "xoxc-your-token",
+        "SLACK_COOKIE": "xoxd-your-cookie"
+      }
+    }
+  }
+}
+```
+
+#### For Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/slack-mcp-server/src/server.js"]
+    }
+  }
+}
+```
+
+Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
+
+### 4. Restart Claude
+
+The Slack tools will now be available.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `slack_health_check` | Verify token validity and show workspace info |
+| `slack_refresh_tokens` | Auto-extract fresh tokens from Chrome |
+| `slack_list_conversations` | List DMs and channels with resolved names |
+| `slack_conversations_history` | Get messages from a channel or DM |
+| `slack_get_full_conversation` | Export full history with threads |
+| `slack_search_messages` | Search across workspace |
+| `slack_send_message` | Send a message |
+| `slack_get_thread` | Get thread replies |
+| `slack_users_info` | Get user details |
+| `slack_list_users` | List workspace users |
+
+## Web UI (for claude.ai)
+
+Since claude.ai doesn't support MCP, you can use the web server:
+
+```bash
+npm run web
+```
+
+Open http://localhost:3000 in your browser. It auto-connects with the default API key (`slack-mcp-local`).
+
+<details>
+<summary><strong>View Web UI Screenshots</strong></summary>
+
+| DMs View | Channels View |
+|----------|---------------|
+| ![DMs](docs/images/demo-main.png) | ![Channels](docs/images/demo-channels.png) |
+
+</details>
+
+### Auto-Start on Login (macOS)
+
+```bash
+# Create LaunchAgent
+cat > ~/Library/LaunchAgents/com.slack-mcp-server.plist << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.slack-mcp-server</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/node</string>
+        <string>/path/to/slack-mcp-server/src/web-server.js</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/path/to/slack-mcp-server</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.slack-mcp-server.plist
+```
+
+## Token Management
+
+Tokens are stored in multiple layers for reliability:
+
+1. **Environment variables** - From MCP config
+2. **Token file** - `~/.slack-mcp-tokens.json` (chmod 600)
+3. **macOS Keychain** - Encrypted persistent storage
+4. **Chrome auto-extraction** - Fallback when tokens expire
+
+### When Tokens Expire
+
+Tokens typically last 1-2 weeks. When they expire:
+
+```bash
+# Option 1: In Claude
+slack_refresh_tokens
+
+# Option 2: CLI
+npm run tokens:auto
+```
+
+## Troubleshooting
+
+### DMs Not Showing
+
+This is handled automatically. The server discovers DMs by calling `conversations.open` for each user (Slack's `conversations.list` doesn't return DMs with browser tokens).
+
+### Rate Limiting
+
+The client implements automatic retry with exponential backoff. If you still hit limits, reduce batch sizes in your queries.
+
+### Claude Desktop Not Seeing Tools
+
+1. Verify JSON syntax in config
+2. Check logs: `~/Library/Logs/Claude/mcp-server-slack.log`
+3. Fully restart Claude Desktop (Cmd+Q, then reopen)
+
+### Chrome Extraction Fails
+
+- Chrome must be running (not just in Dock)
+- Have a Slack tab open at `app.slack.com`
+- Be logged into Slack
+
+## How It Works
+
+This server uses Slack's internal Web API with browser session tokens (`xoxc-` token and `xoxd-` cookie). This provides the same access level as the Slack web interface.
+
+**Why not a Slack App?**
+
+Slack apps require OAuth and cannot access DMs without explicit per-conversation authorization from users. Browser tokens bypass this limitation.
+
+**Trade-offs:**
+- ✅ Full access to all conversations
+- ✅ No per-conversation authorization
+- ❌ Tokens expire every 1-2 weeks
+- ❌ Requires Chrome for token extraction
+- ❌ Not officially supported by Slack
+
+## Security Notes
+
+- Tokens are stored with `chmod 600` (owner read/write only)
+- macOS Keychain provides encrypted storage
+- Never commit tokens to version control
+- Web server only accessible on localhost by default
+
+## Project Structure
+
+```
+slack-mcp-server/
+├── src/
+│   ├── server.js         # MCP server entry point
+│   └── web-server.js     # REST API + Web UI
+├── lib/
+│   ├── token-store.js    # 4-layer token persistence
+│   ├── slack-client.js   # API client with retry logic
+│   ├── tools.js          # MCP tool definitions
+│   └── handlers.js       # Tool implementations
+├── public/
+│   ├── index.html        # Web UI
+│   └── demo.html         # Interactive demo with mock data
+├── scripts/
+│   └── token-cli.js      # Token management CLI
+└── docs/
+    ├── images/           # Screenshots
+    ├── SETUP.md          # Detailed setup guide
+    ├── API.md            # Tool reference
+    ├── WEB-API.md        # REST API reference
+    └── TROUBLESHOOTING.md
+```
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Support
+
+If you find this useful, consider supporting the project:
+
+- [GitHub Sponsors](https://github.com/sponsors/jtalk22)
+- [Ko-fi](https://ko-fi.com/jtalk22)
+- [Buy Me a Coffee](https://www.buymeacoffee.com/jtalk22)
+
+Star the repo if it helped you!
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## Disclaimer
+
+This project uses unofficial Slack APIs. Use at your own risk. The authors are not responsible for any account issues that may arise from using this software.

package/docs/API.md

@@ -0,0 +1,286 @@
+# API Reference
+
+## Tools
+
+### slack_health_check
+
+Check if Slack tokens are valid.
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "status": "OK",
+  "user": "james",
+  "team": "Rêvasser",
+  "token_source": "environment",
+  "token_updated": "2026-01-03T00:00:00Z"
+}
+```
+
+---
+
+### slack_refresh_tokens
+
+Force refresh tokens from Chrome.
+
+**Prerequisites:** Chrome must be running with a Slack tab open (app.slack.com).
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "status": "SUCCESS",
+  "user": "james",
+  "team": "Rêvasser"
+}
+```
+
+---
+
+### slack_list_conversations
+
+List all DMs and channels.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| types | string | "im,mpim" | Conversation types to include |
+| limit | number | 100 | Maximum results |
+
+**Types:**
+- `im` - Direct messages
+- `mpim` - Group DMs
+- `public_channel` - Public channels
+- `private_channel` - Private channels
+
+**Returns:**
+```json
+{
+  "count": 5,
+  "conversations": [
+    {
+      "id": "D063M4403MW",
+      "name": "Gwen Santos",
+      "type": "dm",
+      "user_id": "U05GPEVH7J9"
+    }
+  ]
+}
+```
+
+---
+
+### slack_conversations_history
+
+Get messages from a channel or DM.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| limit | number | 50 | Messages to fetch (max 100) |
+| oldest | string | - | Unix timestamp, get messages after |
+| latest | string | - | Unix timestamp, get messages before |
+| resolve_users | boolean | true | Convert user IDs to names |
+
+**Returns:**
+```json
+{
+  "channel": "D063M4403MW",
+  "message_count": 50,
+  "has_more": true,
+  "messages": [
+    {
+      "ts": "1767368030.607599",
+      "user": "Gwen Santos",
+      "user_id": "U05GPEVH7J9",
+      "text": "Hello!",
+      "datetime": "2026-01-02T15:33:50.000Z",
+      "has_thread": false
+    }
+  ]
+}
+```
+
+---
+
+### slack_get_full_conversation
+
+Export full conversation with threads.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| oldest | string | - | Unix timestamp start |
+| latest | string | - | Unix timestamp end |
+| max_messages | number | 2000 | Max messages (up to 10000) |
+| include_threads | boolean | true | Fetch thread replies |
+| output_file | string | - | Save to file path |
+
+**Timestamps:**
+- Dec 1, 2025 = `1733011200`
+- Jan 1, 2026 = `1735689600`
+
+**Returns:**
+```json
+{
+  "channel": "D063M4403MW",
+  "exported_at": "2026-01-03T16:00:00Z",
+  "total_messages": 150,
+  "date_range": {
+    "oldest": "2025-12-01T00:00:00Z",
+    "latest": "now"
+  },
+  "saved_to": "/Users/james/export.json",
+  "messages": [...]
+}
+```
+
+---
+
+### slack_search_messages
+
+Search messages across the workspace.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| query | string | *required* | Search query |
+| count | number | 20 | Number of results (max 100) |
+
+**Query Syntax:**
+- `from:@username` - From specific user
+- `in:#channel` - In specific channel
+- `has:link` - Has links
+- `before:2026-01-01` - Before date
+- `after:2025-12-01` - After date
+
+**Returns:**
+```json
+{
+  "query": "project update",
+  "total": 25,
+  "matches": [
+    {
+      "ts": "1767368030.607599",
+      "channel": "general",
+      "channel_id": "C05GPEVH7J9",
+      "user": "James Lambert",
+      "text": "Here's the project update...",
+      "datetime": "2026-01-02T15:33:50.000Z",
+      "permalink": "https://..."
+    }
+  ]
+}
+```
+
+---
+
+### slack_send_message
+
+Send a message.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| text | string | *required* | Message text |
+| thread_ts | string | - | Thread to reply to |
+
+**Returns:**
+```json
+{
+  "status": "sent",
+  "channel": "D063M4403MW",
+  "ts": "1767368030.607599",
+  "message": "Hello!"
+}
+```
+
+---
+
+### slack_get_thread
+
+Get all replies in a thread.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| channel_id | string | *required* | Channel or DM ID |
+| thread_ts | string | *required* | Thread parent timestamp |
+
+**Returns:**
+```json
+{
+  "channel": "D063M4403MW",
+  "thread_ts": "1767368030.607599",
+  "message_count": 5,
+  "messages": [
+    {
+      "ts": "1767368030.607599",
+      "user": "James Lambert",
+      "text": "Original message",
+      "datetime": "2026-01-02T15:33:50.000Z",
+      "is_parent": true
+    }
+  ]
+}
+```
+
+---
+
+### slack_users_info
+
+Get user details.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| user_id | string | *required* | Slack user ID |
+
+**Returns:**
+```json
+{
+  "id": "U05GPEVH7J9",
+  "name": "gwen",
+  "real_name": "Gwen Santos",
+  "display_name": "Gwen",
+  "email": "gwen@example.com",
+  "title": "Assistant",
+  "timezone": "America/New_York",
+  "is_bot": false,
+  "is_admin": false
+}
+```
+
+---
+
+### slack_list_users
+
+List all workspace users.
+
+**Parameters:**
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| limit | number | 100 | Maximum users to return |
+
+**Returns:**
+```json
+{
+  "count": 10,
+  "users": [
+    {
+      "id": "U05GPEVH7J9",
+      "name": "gwen",
+      "real_name": "Gwen Santos",
+      "display_name": "Gwen",
+      "email": "gwen@example.com",
+      "is_admin": false
+    }
+  ]
+}
+```