【Claude Code】Discord의 Channels 기능을 확장하는 자작 MCP 서버를 만들어 보았다

지난 기사에서 Claude Code의 Channels 기능을 사용하여 Discord로부터 Claude Code를 조작할 수 있도록 했습니다.

그때 "향후 전망"으로 적어두었던 내용입니다만, 공식 Discord 플러그인은 메시지 주고받기만 가능하며, 채널 생성이나 삭제와 같은 서버 관리 계열의 조작에는 대응하지 않습니다.

학습용 Discord 서버를 Claude Code가 정비해 주기를 바랐기에, 채널 관리가 가능한 MCP 서버를 직접 만들어 보았습니다. 이 기사에서는 그 구현과 도중에 빠졌던 문제점(ハマったポイント)을 공유합니다.

• macOS Sequoia
• Claude Code v2.1.167
• Python 3.12 / uv 0.9.24
• Discord Bot (지난 기사에서 셋업 완료)

먼저, 공식 플러그인(discord@claude-plugins-official)에서 사용할 수 있는 도구를 정리해 두겠습니다.

도구	조작
fetch_messages	메시지 취득 (최대 100건)
reply	메시지 송신 (파일 첨부 가능)
react	리액션 추가
edit_message	송신 완료된 메시지 편집
download_attachment	첨부 파일 다운로드

모두 메시지 조작입니다. 채널의 생성·삭제·이름 변경이나 카테고리 관리와 같은 서버 관리 계열의 조작은 일절 없습니다.

Python으로 Discord Bot을 만든다면 discord.py가 정석이지만, 이번에는 일부러 httpx를 사용하여 Discord REST API를 직접 호출하는 방침으로 정했습니다.

discord.py는 상주형 Bot을 위한 라이브러리로, Bot.run()을 호출하면 독자적인 비동기 이벤트 루프(Event Loop)로 들어갑니다. 반면, MCP 서버는 FastMCP가 내부적으로 독자적인 이벤트 루프를 가지고 있기 때문에, 양자를 공존시키면 경합이 발생하여 제대로 작동하지 않거나 구현이 복잡해질 수 있습니다.

httpx는 독자적인 이벤트 루프를 가지지 않는 비동기 HTTP 클라이언트이므로, FastMCP의 루프 안에서 await 하나로 Discord의 REST API를 호출할 수 있습니다.

최종적으로 채택한 기술 스택은 다음과 같습니다.

컴포넌트	기술
언어	Python 3.12 (3.10 이상에서 동작)
...

최종적으로는 이렇게 되었습니다.

original-tools/
├── pyproject.toml
├── .env # Bot Token & Guild ID (서버 ID)
...

Discord REST API v10을 httpx로 호출하는 클라이언트입니다. 인증은 Authorization: Bot {토큰} 헤더를 붙이기만 하면 됩니다.

# client.py
BASE_URL = "https://discord.com/api/v10"
class DiscordClient:
...

각 조작의 메서드는 이 _request를 사용하여 대응하는 REST API 엔드포인트를 호출할 뿐입니다. 예를 들어 채널 생성이라면 POST /guilds/{guild_id}/channels, 삭제라면 DELETE /channels/{channel_id}와 같은 방식으로 패턴이 동일하므로 생략합니다.

FastMCP의 @mcp.tool() 데코레이터를 붙인 함수가 그대로 Claude Code의 도구가 됩니다.

# tools/channels.py
@mcp.tool()
async def list_channels() -> str:
...

동일한 패턴으로 create_channel, delete_channel, edit_channel, create_category 총 5개를 정의했습니다.

공식 Discord 플러그인은 ~/.claude/channels/discord/access.json에서 채널별 액세스 제어를 관리하고 있습니다. 새로운 채널을 만들어도 이 파일에 채널 ID를 추가하지 않으면 Bot이 반응할 수 없습니다. 매번 수동으로 추가하는 것은 번거로우므로, 채널 생성·삭제 시 자동으로 업데이트되도록 했습니다.

# tools/channels.py
ACCESS_JSON = Path.home() / ".claude" / "channels" / "discord" / "access.json"
def _add_channel_to_access(channel_id: str) -> None:
...

여기서 주의한 점은 삭제 시의 순서입니다. access.json에서 엔트리를 먼저 삭제한 다음 Discord의 채널을 삭제하도록 했습니다.

반대 순서로 하면, Discord 측의 삭제는 성공했지만 access.json 업데이트에 실패했을 경우, 존재하지 않는 채널이 액세스 리스트에 계속 남아 있게 됩니다.

Bot Token과 Guild ID는 .env 파일에서 읽어옵니다.

# .env
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=123456789012345678 # 서버를 우클릭 → "서버 ID 복사"로 취득

지난번 셋업에서는 메시지 관련 권한만 부여했습니다. 채널 관리를 수행하려면 추가로 Manage Channels와 View Channels 권한이 필요합니다.

Discord Developer Portal의 OAuth2 → URL Generator에서 권한을 추가한 URL을 생성하고, Bot을 재초대하면 권한이 업데이트됩니다.

다음 명령어로 MCP 서버를 Claude Code에 등록합니다.

claude mcp add --transport stdio --scope user discord-server-admin -- \
uv run --directory /path/to/original-tools python -m discord_mcp.server

~/.claude/settings.json의 permissions.allow에 아래 내용을 추가하면, 채널 삭제 이외의 툴은 확인 절차 없이 실행됩니다.

{
"permissions": {
"allow": [
...

삭제만은 매번 확인 창이 뜨도록 하여, 실수로 삭제하는 것을 방지하고 있습니다.

Discord의 Channels를 통해 Claude Code에 채널 생성 및 삭제를 요청해 보았습니다.

채널 생성과 삭제 모두 문제없이 동작하고 있습니다. access.json의 자동 업데이트가 작동하고 있으므로, 생성한 채널에서 바로 Bot과 대화할 수 있습니다.

claude mcp add의 기본값은 프로젝트 스코프 (현재 디렉토리에 종속되는 설정)입니다.

스코프	지정 방법	유효 범위
프로젝트 (기본값)	claude mcp add	등록한 디렉토리만
사용자	claude mcp add --scope user	어느 디렉토리에서든

저는 MCP 서버 소스가 있는 디렉토리에서 claude mcp add를 실행해 버려서, 평소 사용하는 ~/Desktop/work에서 MCP 서버가 보이지 않게 되었습니다. 어디서든 사용하고 싶다면 --scope user가 필요합니다.

~/.claude/settings.json에도 mcpServers라는 키를 쓸 수 있지만, MCP 서버의 등록처로는 기능하지 않습니다.

파일	용도
~/.claude.json	MCP 서버 등록처 (claude mcp add가 기록하는 곳)
~/.claude/settings.json	권한 설정 등 (mcpServers를 써도 인식되지 않음)

claude mcp add 명령어를 사용하거나, ~/.claude.json에 직접 작성해야 합니다.

그리하여, 공식 플러그인에 없는 기능을 자작 MCP 서버로 빠르게 보완해 보았습니다. (Claude Code 만세)

이번에는 채널 관리뿐이지만, 동일한 메커니즘으로 역할(Role) 관리나 메시지 일괄 삭제 등도 추가할 수 있습니다. Discord REST API의 엔드포인트에 대응하는 툴 함수를 작성하기만 하면 되므로, 필요할 때마다 확장해 나갈 생각입니다.

감사합니다.