How to build a SlackBot agent using ClickHouse MCP server

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/use-cases/AI_ML/MCP/ai_agent_libraries/slackbot.md)

In this guide, you'll learn how to build a [SlackBot](https://slack.com/intl/en-gb/help/articles/202026038-An-introduction-to-Slackbot) agent.
This bot allows you to ask questions about your ClickHouse data directly from Slack, using natural language. It uses the
[ClickHouse MCP server](https://github.com/ClickHouse/mcp-clickhouse) and [PydanticAI](https://ai.pydantic.dev/mcp/client/#__tabbed_1_1).

Example project

The code for this example can be found in the [examples repository](https://github.com/ClickHouse/examples/blob/main/ai/mcp/slackbot/README.md).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

- You'll need to have [`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed
- You'll need access to a Slack workspace
- You'll need an Anthropic API key, or API key from another LLM provider

Create a Slack App

## Create a Slack App[​](#create-a-slack-app "Direct link to Create a Slack App")

1. Go to [slack.com/apps](https://slack.com/apps) and click `Create New App`.
2. Choose option `From scratch` and give your app a name.
3. Select your Slack workspace.

Install the app to your workspace

## Install the app to your workspace[​](#install-the-app-to-your-workspace "Direct link to Install the app to your workspace")

Next, you'll need to add the app created in the previous step to your workspace.
You can follow the instructions for ["Add apps to your Slack workspace"](https://slack.com/intl/en-gb/help/articles/202035138-Add-apps-to-your-Slack-workspace)
in the Slack documentation.

Configure Slack app settings

## Configure Slack app settings[​](#configure-slack-app-settings "Direct link to Configure Slack app settings")

- Go to `App Home`
  - Under `Show Tabs` → `Messages Tab`: Enable `Allow users to send Slash commands and messages from the messages tab`
  - Go to `Socket Mode`
    - Enable `Socket Mode`
    - Note down the `Socket Mode Handler` for the environment variable `SLACK_APP_TOKEN`
  - Go to `OAuth & Permissions`
    - Add the following `Bot Token Scopes`:
      - `app_mentions:read`
      - `assistant:write`
      - `chat:write`
      - `im:history`
      - `im:read`
      - `im:write`
      - `channels:history`
    - Install the app to your workspace and note down the `Bot User OAuth Token` for the environment variable `SLACK_BOT_TOKEN`.
  - Go to `Event Subscriptions`
    - Enable `Events`
    - Under `Subscribe to bot events`, add:
      - `app_mention`
      - `assistant_thread_started`
      - `message:im`
    - Save Changes

Add environment variables ()

## Add environment variables (`.env`)[​](#add-env-vars "Direct link to add-env-vars")

Create a `.env` file in the project root with the following environment variables
which will allow your app to connect to [ClickHouse's SQL playground](https://sql.clickhouse.com/).

```
SLACK_BOT_TOKEN=your-slack-bot-token
SLACK_APP_TOKEN=your-slack-app-level-token
ANTHROPIC_API_KEY=your-anthropic-api-key
CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_PORT=8443
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
CLICKHOUSE_SECURE=true
```

You can adapt the ClickHouse variables to use your own ClickHouse server
or Cloud instance, if you would prefer.

Using the bot

## Using the bot[​](#using-the-bot "Direct link to Using the bot")

1. **Start the bot:**

   ```
   uv run main.py
   ```
2. **In Slack:**

   - Mention the bot in a channel: `@yourbot Who are the top contributors to the ClickHouse git repo?`
   - Reply to the thread with a mention: `@yourbot how many contributions did these users make last week?`
   - DM the bot: `Show me all tables in the demo database.`

The bot will reply in the thread, using all previous thread messages as context
if applicable.

**Thread Context:**
When replying in a thread, the bot loads all previous messages (except the current one) and includes them as context for the AI.

**Tool Usage:**
The bot uses only the tools available via MCP (e.g., schema discovery, SQL execution) and will always show the SQL used and a summary of how the answer was found.

- [Prerequisites](#prerequisites)- [Create a Slack App](#create-a-slack-app)- [Install the app to your workspace](#install-the-app-to-your-workspace)- [Configure Slack app settings](#configure-slack-app-settings)- [Add environment variables (`.env`)](#add-env-vars)- [Using the bot](#using-the-bot)

Was this page helpful?