Slack Note Capture MCP Server

A Model Context Protocol (MCP) server that enables two-way communication between Claude Code and Slack. Post messages, read threads, and wait for user replies — enabling remote conversations when you're away from your machine.

New to MCP servers? See QUICKSTART.md for step-by-step setup instructions with screenshots-style guidance.

Prerequisites

• Node.js 18+ — nodejs.org
• Claude Code — Anthropic's CLI tool (claude.ai/claude-code)
• Slack workspace — Free plan works; you need permission to install apps

Features

• Two-way conversations — Claude asks questions via Slack, you reply from your phone
• Thread support — Post to threads and read thread replies
• Wait for replies — Poll threads until you respond (configurable timeout)
• Channel operations — Read history, search messages, list channels
• File handling — Get file info and download shared files

Use Cases

Remote Conversations

Claude asks a question via Slack, you reply from your phone, Claude continues working.

Task Notifications

Claude posts completion updates to a Slack channel so you know when work is done.

Note Capture

Send ideas, links, and voice notes to Slack for Claude to process later.

Async Workflows

Start a task, go about your day, get notified when input is needed.

Installation

git clone https://github.com/larrygmaguire-hash/slack-note-capture.git
cd slack-note-capture
npm install

Slack App Setup

Detailed instructions: See QUICKSTART.md for step-by-step guidance with explanations.

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name your app (e.g., Claude Assistant) and select your workspace
3. Go to OAuth & Permissions and add these Bot Token Scopes:

Scope	Purpose
channels:history	Read messages from public channels
channels:read	List channels
chat:write	Post messages
files:read	Access shared files
groups:history	Read messages from private channels (optional)
groups:read	List private channels (optional)

4. Click Install to Workspace and authorise
5. Copy the Bot User OAuth Token (starts with xoxb-)
6. Create a channel for Claude and get its Channel ID (right-click channel → View details → scroll to bottom)
7. Invite the bot: /invite @YourAppName in the channel

Configuration

Tool Permissions (Required)

By default, Claude Code prompts for approval each time an MCP tool is used. For Slack tools to work without interruption (especially slack_wait_for_reply which blocks execution), you must pre-approve them.

Add to ~/.claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "mcp__slack-note-capture__slack_read_messages",
      "mcp__slack-note-capture__slack_post_message",
      "mcp__slack-note-capture__slack_post_to_thread",
      "mcp__slack-note-capture__slack_read_thread",
      "mcp__slack-note-capture__slack_wait_for_reply",
      "mcp__slack-note-capture__slack_get_file",
      "mcp__slack-note-capture__slack_download_file",
      "mcp__slack-note-capture__slack_list_channels",
      "mcp__slack-note-capture__slack_search_messages"
    ]
  }
}

Alternative (VSCode): When prompted for tool approval, select "Yes, allow for this project (just you)" — this persists the permission in ~/.claude.json.

Important: Restart Claude Code after changing permissions.

Environment Variables

Variable	Required	Description
SLACK_BOT_TOKEN	Yes	Bot User OAuth Token from your Slack app
SLACK_CHANNEL_ID	No	Default channel ID for operations

Claude Code Configuration

Add to your ~/.claude.json:

{
  "mcpServers": {
    "slack-note-capture": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/slack-note-capture/src/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here",
        "SLACK_CHANNEL_ID": "C0123456789"
      }
    }
  }
}

Available Tools

slack_post_message

Post a message to a channel. Returns the message timestamp (ts) for thread operations.

{
  channel_id: "C0123456789",  // optional, uses default if not provided
  text: "Hello from Claude!"
}

slack_post_to_thread

Reply to an existing message thread.

{
  channel_id: "C0123456789",  // optional
  thread_ts: "1234567890.123456",  // required - parent message timestamp
  text: "This is a thread reply"
}

slack_read_thread

Read all replies in a thread. Useful for checking responses to your messages.

{
  channel_id: "C0123456789",  // optional
  thread_ts: "1234567890.123456"  // required
}

slack_wait_for_reply

The key tool for remote conversations. Posts a message and polls for a user reply.

{
  channel_id: "C0123456789",  // optional
  message: "I need your input on X. Please reply in this thread.",
  poll_interval_seconds: 30,  // default: 30
  timeout_minutes: 15  // default: 15
}

Or monitor an existing thread:

{
  thread_ts: "1234567890.123456",
  poll_interval_seconds: 30,
  timeout_minutes: 15
}

Returns either:

• Success with the user's reply text
• Timeout with a hint to check manually later

slack_read_messages

Read recent messages from a channel.

{
  channel_id: "C0123456789",  // optional
  days_back: 7,  // default: 7
  limit: 100  // default: 100
}

slack_list_channels

List available channels to find channel IDs.

{
  types: "public_channel,private_channel"  // default
}

slack_search_messages

Search for messages containing specific text.

{
  query: "workshop idea",
  channel_id: "C0123456789"  // optional but recommended
}

slack_get_file

Get information about a shared file.

{
  file_id: "F0123456789"
}

slack_download_file

Download a file to local storage.

{
  file_id: "F0123456789",
  save_path: "/path/to/save/file.pdf"
}

Example: Remote Question/Answer

Claude: I'm working on the report but need to know which format you prefer.
        Let me ask you via Slack so you can respond from your phone.

[Claude calls slack_wait_for_reply with question about format]
[User receives Slack notification on phone]
[User replies in thread: "PDF please"]
[Claude receives reply and continues work]

Example: Task Completion Notification

When Claude finishes a task, it posts a summary to Slack:

Claude: [completes grading 15 assignments]
        Let me notify you that the task is complete.

[Claude calls slack_post_message: "✓ Grading complete — 15 assignments processed, feedback docs saved to Google Drive"]
[User receives notification on phone]

This is useful for long-running tasks where you've stepped away from your machine.

Finding Channel IDs

Channel IDs are not the same as channel names. To find a channel ID:

1. Use the slack_list_channels tool, or
2. In Slack: right-click a channel → "View channel details" → scroll to bottom

Channel IDs look like: C0A9WLH9KH9 (public) or G0A9WLH9KH9 (private)

Troubleshooting

"not_in_channel" error

The bot needs to be added to the channel. In Slack, type /invite @YourBotName in the channel.

Thread replies not appearing

Make sure you're replying in the thread, not as a new message in the channel. In Slack mobile, tap the message first, then reply.

Timeout on wait_for_reply

The default timeout is 15 minutes. Increase with timeout_minutes, or call slack_read_thread later to check manually.

MCP not loading

1. Check ~/.claude.json syntax is valid JSON
2. Restart Claude Code / VS Code
3. Verify the path to index.js is correct

Testing Your Setup

After configuration, restart Claude Code and test:

List my Slack channels

If successful, you'll see your workspace channels. Then test posting:

Post "Hello from Claude!" to my Slack inbox

Check your Slack channel for the message. For full testing steps including the reply feature, see QUICKSTART.md.

Security Notes

• Never commit your SLACK_BOT_TOKEN to git
• The token is stored in ~/.claude.json which is machine-specific
• Each machine needs its own configuration

Version History

• 2.0.0 — Added two-way communication: slack_read_thread, slack_post_to_thread, slack_wait_for_reply
• 1.0.0 — Initial release: basic read/post/file operations

Licence

MIT