# Slack User MCP Server

A personal [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects to Slack using your **user token** (`xoxp-...`), giving AI agents full access to your workspace — including message search, channel history, DMs, and posting as yourself.

Unlike bot-token-based Slack integrations, this server acts as **you**, so it can access any channel you're a member of (including private channels and DMs) and use the Slack search API.

## Features

- **Search messages** — Full Slack search syntax (`from:me`, `in:#channel`, `has:link`, date filters, etc.)
- **Channel history** — Read messages from any channel, DM, or group message you're in
- **Post messages** — Send messages as yourself (not as a bot)
- **User lookup** — Find users by name or email
- **Thread reading** — Fetch all replies in a thread
- **Auth verification** — Confirm your connection and identity

## Tools

| Tool | Description |
|------|-------------|
| `slack_search_messages` | Search messages with Slack query syntax |
| `slack_list_channels` | List channels (public, private, DMs) |
| `slack_get_channel_history` | Read recent messages from a channel |
| `slack_post_message` | Send a message as yourself |
| `slack_lookup_user` | Find users by name or email |
| `slack_get_user_info` | Get detailed user profile by ID |
| `slack_get_thread` | Read all replies in a thread |
| `slack_auth_test` | Verify your connection |

## Setup

### 1. Create a Slack App and Get a User Token

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app **From scratch**
2. Under **OAuth & Permissions**, add these **User Token Scopes**:
   - `search:read`
   - `channels:read`, `channels:history`
   - `groups:read`, `groups:history`
   - `im:read`, `im:history`
   - `mpim:read`, `mpim:history`
   - `users:read`, `users:read.email`
   - `chat:write`
3. Install the app to your workspace
4. Copy the **User OAuth Token** (starts with `xoxp-`)

### 2. Install Dependencies and Build

```bash
cd slack-user-mcp-server
npm install
npm run build
```

### 3. Connect to Claude Desktop

Add this to your Claude Desktop config:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "slack-personal": {
      "command": "node",
      "args": ["/path/to/slack-user-mcp-server/dist/index.js"],
      "env": {
        "SLACK_USER_TOKEN": "xoxp-your-token-here"
      }
    }
  }
}
```

> **Note**: If you use a Node version manager like `fnm` or `nvm`, use the full path to `node` instead of just `"node"`. Find it with `fnm exec --using=default -- which node` or `nvm which default`.

### 4. Restart Claude Desktop

Quit and reopen Claude Desktop. The server will appear in your MCP connections.

## Example Queries

Once connected, you can ask your AI assistant things like:

- "Search for my recent Slack messages" — uses `from:me`
- "What's the latest in #general?" — channel history
- "Find messages about the Q1 budget" — full-text search
- "Who is on the marketing team?" — user lookup
- "Send a message to #general saying the build is green" — post as yourself

## Search Syntax

The search tool supports all [Slack search modifiers](https://slack.com/help/articles/202528808):

| Modifier | Example | Description |
|----------|---------|-------------|
| `from:` | `from:me` or `from:@username` | Messages from a user |
| `in:` | `in:#channel` | Messages in a channel |
| `has:` | `has:link`, `has:reaction` | Filter by attributes |
| `before:` / `after:` | `after:2024-01-01` | Date range |
| `is:` | `is:thread` | Threaded messages only |

## Tech Stack

- TypeScript
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Slack Web API (via fetch)
- Zod for input validation
- stdio transport