SlackBot 에이전트를 ClickHouse MCP 서버로 빌드하기

이 가이드에서는 SlackBot 에이전트를 빌드하는 방법을 배워요. 이 봇은 자연어로 Slack에서 바로 ClickHouse 데이터에 대해 질문할 수 있게 해줘요. ClickHouse MCP 서버와 PydanticAI를 사용해요.

출처: 문서

본문

이 예제의 코드는 examples 저장소에서 확인할 수 있어요.

준비 사항 (Prerequisites)

uv가 설치되어 있어야 해요.
Slack 워크스페이스에 접근할 수 있어야 해요.
Anthropic API 키 또는 다른 LLM 제공자의 API 키가 필요해요.

1. Slack 앱 만들기 (Create a Slack App)

slack.com/apps로 이동해 Create New App을 클릭해요.
From scratch 옵션을 선택하고 앱 이름을 지어줘요.
Slack 워크스페이스를 선택해요.

2. 앱을 워크스페이스에 설치하기

이전 단계에서 만든 앱을 워크스페이스에 추가해야 해요. Slack 문서의 “Add apps to your Slack workspace” 지침을 따르면 돼요.

3. Slack 앱 설정 구성하기

App Home으로 이동
- Show Tabs → Messages Tab에서 아래 항목 활성화: Allow users to send Slash commands and messages from the messages tab
- Socket Mode로 이동
  - Socket Mode 활성화
  - 환경 변수 SLACK_APP_TOKEN을 위한 Socket Mode Handler를 적어둬요.
- OAuth & Permissions로 이동
  - 다음 Bot Token Scopes를 추가해요:
    - app_mentions:read
    - assistant:write
    - chat:write
    - im:history
    - im:read
    - im:write
    - channels:history
  - 앱을 워크스페이스에 설치하고 환경 변수 SLACK_BOT_TOKEN을 위한 Bot User OAuth Token을 적어둬요.
- Event Subscriptions로 이동
  - Events 활성화
  - Subscribe to bot events 아래에 추가:
    - app_mention
    - assistant_thread_started
    - message:im
  - 변경 사항 저장

4. 환경 변수 추가 (`.env`)

프로젝트 루트에 다음 환경 변수를 담은 .env 파일을 만들어요. 이 변수들을 통해 앱이 ClickHouse의 SQL 플레이그라운드에 연결할 수 있어요.

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

원한다면 ClickHouse 변수를 자신의 ClickHouse 서버나 Cloud 인스턴스에 맞게 조정할 수 있어요.

5. 봇 사용하기

봇 시작하기:

uv run main.py

Slack에서:

채널에서 봇을 멘션: @yourbot Who are the top contributors to the ClickHouse git repo?
스레드에서 멘션으로 답장: @yourbot how many contributions did these users make last week?
봇에게 DM: Show me all tables in the demo database.

봇은 스레드에서 응답하며, 가능하면 이전 스레드 메시지를 모두 문맥으로 사용해요.

스레드 문맥 (Thread Context): 스레드에서 답장할 때 봇은 현재 메시지를 제외한 모든 이전 메시지를 불러와 AI의 문맥으로 포함해요.

도구 사용 (Tool Usage): 봇은 MCP를 통해 제공되는 도구(예: 스키마 탐색, SQL 실행)만 사용하며, 사용된 SQL과 답을 어떻게 찾았는지 요약을 항상 보여줘요.

SlackBot 에이전트를 ClickHouse MCP 서버로 빌드하기