slack-messages

Fuzzy search and browse Slack messages from the command line or as an MCP server.

Features

• Fuzzy search with typo tolerance across all your Slack messages
• Browse recent messages, users, and channels
• User name resolution - shows display names instead of user IDs
• Context display - see messages before/after each match
• Filter by sender or date range
• Thread support - indexes thread replies alongside parent messages
• Incremental updates - quickly fetch only new messages
• Multiple interfaces - CLI or MCP server

Requirements

• Node.js 22+
• Slack user token with appropriate scopes (see below)

Installation

npm

npm install -g @cardmagic/slack-messages

From source

git clone https://github.com/cardmagic/slack-messages.git
cd slack-messages
pnpm install
pnpm build
npm link

Getting a Slack Token

You need a User OAuth Token (starts with xoxp-), NOT a Bot token.

Important: Bot tokens (xoxb-...) only see the bot's own empty DMs. You must use a User token (xoxp-...) to access your messages.

Required Scopes

Add these under "User Token Scopes" (not "Bot Token Scopes"):

Scope	Purpose
channels:history	Read public channel messages
groups:history	Read private channel messages
im:history	Read DM messages
mpim:history	Read group DM messages
users:read	Get user display names
channels:read	List public channels
groups:read	List private channels
im:read	List DMs
mpim:read	List group DMs

Step-by-Step: Create a Slack App

1. Go to the Slack API portal

   • Visit api.slack.com/apps
   • Sign in to your Slack workspace if prompted

2. Create a new app

   • Click "Create New App"
   • Choose "From scratch"
   • Enter a name (e.g., "Message Search")
   • Select your workspace
   • Click "Create App"

3. Add User Token Scopes (this is critical!)

   • In the left sidebar, click "OAuth & Permissions"
   • Scroll down to find "User Token Scopes"
   • ⚠️ NOT "Bot Token Scopes" - that's a different section!
   • Click "Add an OAuth Scope" and add ALL of these:
     • channels:history
     • channels:read
     • groups:history
     • groups:read
     • im:history
     • im:read
     • mpim:history
     • mpim:read
     • users:read

4. Install the app to your workspace

   • Scroll back up to "OAuth Tokens for Your Workspace"
   • Click "Install to Workspace"
   • Review the permissions and click "Allow"

5. Copy the correct token

   • After installing, you'll see TWO tokens on the OAuth page:
     • ✅ "User OAuth Token" - starts with xoxp- - USE THIS ONE
     • ❌ "Bot User OAuth Token" - starts with xoxb- - don't use this
   • Copy the xoxp- token

6. Add it to slack-messages

   slack-messages auth
   # Paste your token when prompted (input is hidden)
   

Verify Your Token

After adding your token, verify it's correct:

slack-messages index

If you see "Messages: 0" but you know you have messages, you likely used a Bot token by mistake. Go back to step 5 and get the User OAuth Token.

Security Notes

• Your token is stored locally in ~/.slack-messages/config.json
• Never commit or share your token
• You can revoke the token anytime from api.slack.com/apps

Usage

Initial Setup

# Add your Slack workspace (token is prompted securely)
slack-messages auth

# Build the search index (fetches all messages)
slack-messages index

# For incremental updates later
slack-messages index --update

CLI Commands

Browse Commands

# Show most recent messages
slack-messages recent

# List users by recent activity
slack-messages contacts --limit 10

# List channels/DMs with message counts
slack-messages conversations

# Show recent messages from someone
slack-messages from "John Smith"

# Show full conversation in a channel
slack-messages thread "general" --after 2024-12-01

Search Commands

# Search for messages
slack-messages search "quarterly report"

# Filter by sender
slack-messages search "project update" --from "Sarah"

# Filter by date
slack-messages search "meeting" --after 2024-01-01

# Adjust result count and context
slack-messages search "deadline" --limit 20 --context 5

# Show index statistics
slack-messages stats

Workspace Management

# List configured workspaces
slack-messages workspaces

# Remove a workspace
slack-messages remove T0123456789

Search Options

Option	Description
-f, --from <sender>	Filter by sender name
-a, --after <date>	Only messages after date (YYYY-MM-DD)
-l, --limit <n>	Max results (default: 10)
-c, --context <n>	Messages before/after (default: 2)

MCP Server

Run as an MCP server for Claude Code integration:

slack-messages --mcp
# or
slack-messages mcp

Add to your Claude Code configuration:

claude mcp add --transport stdio slack-messages -- slack-messages --mcp

Or manually in your MCP config:

{
  "mcpServers": {
    "slack-messages": {
      "command": "npx",
      "args": ["-y", "@cardmagic/slack-messages", "--mcp"]
    }
  }
}

Available MCP Tools:

Tool	Description
search_messages	Search messages with fuzzy matching
recent_messages	Get most recent messages
list_contacts	List users by activity
list_conversations	List channels/DMs with counts
get_thread	Get conversation in a channel
get_message_stats	Get index statistics

How It Works

1. Authentication: Store your Slack user token locally
2. Indexing: Fetch messages via Slack API and build local indexes:
   • Lists all conversations (channels, DMs, group DMs)
   • Fetches message history for each conversation
   • Fetches thread replies for messages with replies
   • Caches user information for name resolution
3. Storage: Index files in ~/.slack-messages/:
   • config.json - Workspace tokens
   • index.db - SQLite FTS5 database
   • fuzzy.json - MiniSearch index for typo tolerance
   • stats.json - Index statistics and cursors for incremental updates
   • users.json - Cached user information

Rate Limiting

The Slack API has rate limits. The tool uses the official @slack/web-api client which handles retries automatically. For large workspaces, initial indexing may take a while.

License

MIT