slack-messages

January 4, 2026 · View on GitHub

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"):

ScopePurpose
channels:historyRead public channel messages
groups:historyRead private channel messages
im:historyRead DM messages
mpim:historyRead group DM messages
users:readGet user display names
channels:readList public channels
groups:readList private channels
im:readList DMs
mpim:readList group DMs

Step-by-Step: Create a Slack App

  1. Go to the Slack API portal

  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

OptionDescription
-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:

ToolDescription
search_messagesSearch messages with fuzzy matching
recent_messagesGet most recent messages
list_contactsList users by activity
list_conversationsList channels/DMs with counts
get_threadGet conversation in a channel
get_message_statsGet 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