A minimal starter template for building AI-powered Slack agents with Bolt for Python and the Claude Agent SDK using models from Anthropic. Works with the Slack MCP Server to search messages, read channels, send messages, and manage canvases — all from within your agent.

The starter agent interacts with users through four entry points:

• App Home — Displays a welcome message with instructions on how to interact.
• Direct Messages — Users message the agent directly. It responds in-thread, maintaining context across follow-ups.
• Channel @mentions — Mention the agent in any channel to get a response without leaving the conversation.
• Assistant Panel — Users click Add Agent in Slack, select the agent, and pick from suggested prompts or type a message.

The template also includes one example tool (emoji reactions). Add your own tools to customize it for your use case.

When connected to the Slack MCP Server, the agent can search messages and files, read channel history and threads, send and schedule messages, and create and update canvases. When deployed with OAuth (HTTP mode), the agent automatically connects to the Slack MCP Server using the user's token.

Before getting started, make sure you have a development workspace where you have permissions to install apps.

Join the Slack Developer Program for exclusive access to sandbox environments for building and testing your apps, tooling, and resources created to help you build and grow.

Install the Slack MCP and Skills Plugin so your coding agent can create, run, and deploy Slack apps, look up Web API methods and scopes, and build Block Kit without guessing.

Run this in a Claude Code session:

/plugin install slack@claude-plugins-official

Run this in your terminal:

codex plugin marketplace add slackapi/slack-skills-plugin
codex plugin add slack@slack

Run this in a Cursor Agent chat:

/add-plugin slack

Install the skills with npx skills, using your agent's identifier:

npx skills add slackapi/slack-skills-plugin -y -a <agent>

# For example, OpenCode
npx skills add slackapi/slack-skills-plugin -y -a opencode

slack login

slack create my-starter-agent --template slack-samples/bolt-python-starter-agent --subdir claude-agent-sdk
cd my-starter-agent

SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN

SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN

git clone https://github.com/slack-samples/bolt-python-starter-agent.git my-starter-agent
cd my-starter-agent

python3 -m venv .venv
source .venv/bin/activate  # for Windows OS, .\.venv\Scripts\Activate instead should work

pip install -e ".[dev]"

This app uses Claude through the Claude Agent SDK.

1. Create an API key from your Anthropic dashboard.
2. Rename .env.sample to .env.
3. Save the Anthropic API key to .env:

ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY

slack run

python3 app.py

ngrok http 3000

slack install -E local

SLACK_CLIENT_ID=YOUR_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect

slack run app_oauth.py

SLACK_BOT_TOKEN=xoxb-YOUR_BOT_TOKEN
SLACK_CLIENT_ID=YOUR_CLIENT_ID
SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET
SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET
SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect

python3 app_oauth.py

Once the agent is running, there are several ways to interact:

App Home — Open the agent in Slack and click the Home tab. You'll see a welcome message with instructions on how to interact.

Direct Messages — Open a DM with the agent. You'll see suggested prompts like Write a Message, Summarize, and Brainstorm — pick one or type your own message. The agent replies in a thread. Send follow-up messages in the same thread and the agent will maintain the full conversation context.

Channel @mentions — Invite the agent to a channel by typing /invite @agent-name in the message box, then @mention it followed by your message. The agent responds in a thread so the channel stays clean.

Assistant Panel — Click Add Agent in the top-right corner of Slack, select the agent from the list, then pick a suggested prompt or type a message.

# Run ruff check from root directory for linting
ruff check

# Run ruff format from root directory for code formatting
ruff format

manifest.json is a configuration for Slack apps. With a manifest, you can create an app with a pre-defined configuration, or adjust the configuration of an existing app.

app.py is the entry point for the application and is the file you'll run to start the server. This project uses AsyncApp from Bolt for Python, with all handlers running asynchronously.

app_oauth.py is an alternative entry point that runs the app in HTTP mode instead of Socket Mode. This is intended for deployments that use OAuth for app distribution. See the HTTP Mode section under Development for setup instructions.

Every incoming request is routed to a "listener". This directory groups each listener based on the Slack Platform feature used.

/listeners/events — Handles incoming events:

• app_home_opened.py — Publishes the App Home view with a welcome message and MCP status.
• app_mentioned.py — Responds to @mentions in channels.
• message.py — Responds to direct messages from users.

/listeners/actions — Handles interactive components:

• feedback_buttons.py — Handles thumbs up/down feedback on agent responses.

/listeners/views — Builds Block Kit views:

• app_home_builder.py — Constructs the App Home Block Kit view.
• feedback_builder.py — Creates the feedback button block attached to responses.

The agent.py file configures the Claude Agent SDK with a system prompt, tools registered via an MCP server, and a run_agent() async function that handles sending queries and collecting responses.

The deps.py file defines the AgentDeps dataclass passed to the agent at runtime, providing access to the Slack client and conversation context.

The tools directory contains one example tool (emoji reaction) defined using the @tool decorator from the Claude Agent SDK.

The store.py file implements a thread-safe in-memory session ID store, keyed by channel and thread. The Claude Agent SDK manages conversation history server-side via sessions, so only session IDs need to be tracked locally for resuming conversations.

If you see an error like:

Failed to connect to MCP server 'streamable_http: https://mcp.slack.com/mcp': HTTP error 400 (Bad Request)

This means the Slack MCP feature has not been enabled for your app. There is no manifest property for this yet, so it must be toggled on manually:

1. Run slack app settings to open your app's settings page (or visit api.slack.com/apps and select your app)
2. Navigate to Agents & AI Apps in the left-side navigation
3. Toggle Slack Model Context Protocol on