💬 kakao-mcp-ccomajeon

카카오톡 계정 하나를 서버 데몬에 연결해 AI·터미널·웹에서 쓰는 비공식 MCP 서버

AI는 허용된 대화를 읽고 메시지를 보낼 수 있고, 사람은 방별 권한과 승인 절차로 그 범위를 정합니다.

개발·관리: ccomajeon

한눈에 보기 · 전체 구조 · 통신 구간 · 동작 흐름 · 권한 검사 · 기능 · 설치 · 개발

한눈에 보기

Related MCP server: KakaoTalk Local MCP

전체 구조

데몬 하나가 카카오톡 연결을 쥐고 있고, AI·CLI·웹은 모두 그 데몬의 MCP 클라이언트입니다. 클라이언트 쪽은 카카오 계정 정보를 읽지 않고, 자기 세션을 따로 열지도 않습니다.

archify로 코드 근거를 붙여 그린 구조도입니다. 노드마다 근거 코드 링크가 달린 인터랙티브 버전은 docs/diagrams/architecture.html을 내려받아 브라우저로 열어 보세요. 이 README의 다른 다이어그램도 모두 archify로 그렸고, 원본 정의(*.archify.json)는 docs/diagrams에 있습니다.

💡 AI가 같은 서버에 있으면 SSH 없이 127.0.0.1:8787로 바로 연결합니다. MCP 포트는 서버 밖으로 열지 않습니다.

모듈 구성

TypeScript와 Node.js로 만든 npm workspaces 모노레포입니다. 아래쪽 패키지일수록 카카오 서버에 가깝습니다.

• TypeScript 모노레포: npm workspaces로 통신·계정 처리·클라이언트·실행 앱을 나눕니다.

• 프로토콜 처리: LOCO 패킷의 헤더·길이·정수 범위를 검사하고 BSON 본문을 직렬화·역직렬화합니다. 잘린 패킷과 잘못된 입력은 오류로 거부합니다.

• 실시간 메시지: 용량이 제한된 원형 버퍼에 수신 이벤트를 넣고 커서로 새 항목을 조회합니다. 커서는 메모리상의 위치이며 재시작 후 보존되는 체크포인트가 아닙니다.

• 권한과 저장: 계정 세션·SQLite 저장소·방별 읽기/전송 정책·승인·중복 요청 처리를 core에 모읍니다.

• 보안 개선: 승인 응답 재사용, 방 읽기 상한, 웹 사진 표시, 링크 미리보기의 주소 검증을 강화했습니다.

• 배포: esbuild로 실행 프로그램 10개를 ESM 파일에 번들링합니다. 배포 패키지는 별도의 런타임 의존성 다운로드 없이 설치할 수 있으며, 웹 정적 파일과 의존성 라이선스 고지를 포함합니다.

• 검증: Node 테스트 러너로 단위·격리 통합 테스트를 실행하고, TypeScript 검사와 실제 패키지 설치·명령 실행 검사로 확인합니다.

통신 구간별 정리

요청 하나가 AI에서 카카오 서버까지 가는 동안 거치는 구간입니다.

AI 클라이언트와 데몬은 한 줄에 JSON 하나씩 주고받습니다. 로그는 stderr로만 내보내고 stdout은 통신 전용입니다.

// AI → 데몬: 도구 호출
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"read_messages","arguments":{"chatId":"…","mode":"recent"}}}

// 데몬 → AI: 결과 (받은 메시지는 항상 untrusted 데이터로 표시)
{"jsonrpc":"2.0","id":7,"result":{"content":[{"type":"text","text":"…"}]}}

지원 메서드: initialize, tools/list, tools/call, ping, resources/subscribe 등. 요청은 64KiB, 응답은 1MiB, 동시 도구 실행은 16개까지 받습니다.

동작 흐름

1. 처음 설치하고 로그인할 때

사람이 설치 마법사에서 계정 정보를 입력하고, 휴대폰에서 기기 인증을 직접 승인합니다. 이후로는 데몬이 연결을 계속 유지합니다.

• 다른 PC가 이미 쓰고 있으면 기본으로 중단하고, 자동으로 로그아웃시키지 않습니다.

• 자동 재로그인 정보 저장은 선택입니다. 저장하더라도 최대 24시간에 3회로 제한하고, 추가 인증이 필요하면 멈춥니다.

2. AI가 대화를 읽을 때

처음 여는 방(닫힌 방)이면 같은 호출 안에서 사람에게 확인 창을 띄웁니다.

3. AI가 메시지를 보낼 때

모든 쓰기 작업에는 AI가 정한 UUID requestId가 붙습니다. 결과가 불확실할 때 같은 ID로 확인하므로 중복 전송이 일어나지 않습니다.

4. 새 메시지를 받을 때

• 저장과 열람은 별개입니다. 수신 메시지는 모두 로컬 SQLite에 저장되지만, AI가 읽으려면 읽기 권한을 다시 통과해야 합니다.

• 변경 알림(kakao://rooms/{chatId}/messages 구독)에는 본문·작성자를 담지 않습니다. 본문은 항상 read_messages로 읽습니다.

• 웹 화면의 SSE는 연결·방 목록 같은 상태 알림만 보내고 메시지 본문은 보내지 않습니다. 본문은 방 기록을 조회해 읽습니다.

• claim/ack_message_events는 재시작에도 남는 SQLite 이벤트 큐를, read_messages의 wait·recent는 메모리의 원형 버퍼를 읽습니다.

권한은 어떻게 검사하나요?

요청은 아래 순서로 검사하고, 하나라도 거절하면 멈춥니다.

레이어 3(기능 플래그)은 데몬이 혼자 하는 백그라운드 작업 설정이라 이 검사 순서에는 들어가지 않습니다. 자세한 설계는 에이전트 모드와 설정 레이어를 보세요.

어떤 기능이 있나요?

MCP 도구 목록

기본 16개에 선택 묶음 25개를 더하면 총 41개입니다. 묶음을 켜는 것과 방 접근 권한을 주는 것은 별개입니다.

도구별 상세 계약은 MCP 도구와 권한 계약에 있습니다.

설치와 사용법

1. 서버 준비와 설치

서버에는 Linux/systemd, Git, sudo, Node.js 22.18 이상과 npm이 필요합니다. Node는 서비스 계정에서도 실행할 수 있는 시스템 경로에 설치하세요. 사용자 홈의 nvm 설치는 systemd 서비스에서 접근이 막힐 수 있습니다. Windows/macOS에서는 기존 Linux 서버에 연결하는 클라이언트로 사용합니다.

패키지 파일을 서버로 옮기고, 파일이 있는 디렉터리에서 실행합니다.

node --version
npm --version
sudo npm install --global --prefix /usr/local ./kakao-mcp-ccomajeon-0.2.0-rebuild.3.tgz
/usr/local/bin/kakao-mcp --version
/usr/local/bin/kakao-mcp setup

버전은 0.2.0-rebuild.3이어야 합니다. setup은 일반 사용자로 시작하고, 설치 과정에서 필요한 sudo 요청에 응답하세요.

마법사에서 다음 순서로 진행합니다.

1. 새 Linux 서버 설치(2)를 선택합니다.

2. 포트는 기본값 8787을 사용하거나 원하는 포트를 지정합니다.

3. 카카오 계정 정보를 터미널에 입력하고 휴대폰의 로그인·기기 인증 요청을 직접 승인합니다.

4. 자동 재로그인 정보 저장 여부를 선택합니다. 에이전트 모드는 처음에는 기본 ask를 유지합니다.

5. 표시된 설치 내용을 확인하고 서비스 등록·시작을 승인합니다.

설치 경로는 /var/lib/kakao-mcp, 서비스는 kakao-mcp.service입니다. 계정 하나의 연결은 이 서비스 하나가 유지합니다. 설치 후 같은 계정으로 kakao-mcp-mcp를 별도로 실행하지 마세요.

systemctl status kakao-mcp --no-pager
kakao-mcp setup --doctor

현재 버전의 실제 계정 로그인·송수신은 아직 검증하지 않았습니다. 시스템 설치·로그인 과정에 문제가 생기면 아래 진단 명령으로 확인하세요.

2. Codex·Claude 등 AI에 연결

npm install --global ./kakao-mcp-ccomajeon-0.2.0-rebuild.3.tgz
kakao-mcp setup

마법사에서 기존 데몬 연결(1)을 선택하고 user@server 또는 SSH 별칭과 데몬 포트를 입력합니다. 여기서 user@server는 실제 SSH 사용자·서버 주소로 바꾸세요. 마법사가 만든 ~/.config/kakao-mcp/mcp.json과 출력한 AI별 등록 명령을 사용합니다. 전역 설치 위치에 쓰기 권한이 없다면 시스템 전역 설치 권한을 사용하거나 쓰기 가능한 npm prefix를 설정하세요.

설정 JSON만 필요하면 다음 명령을 사용합니다. --config는 JSON을 출력하며, 설정 저장이나 Codex 등록을 자동 수행하지 않습니다.

# 같은 컴퓨터의 데몬
kakao-mcp setup --config --listen 127.0.0.1:8787

# 다른 서버의 데몬
kakao-mcp setup --config --ssh user@server --listen 127.0.0.1:8787

AI 클라이언트 재시작 후 다음과 같이 요청할 수 있습니다.

• 💬 “카카오톡 연결 상태를 확인해 줘.”

• 💬 “대화방 목록을 보여 줘.”

• 💬 “개발팀 방의 최근 대화를 읽고 요약해 줘.”

• 💬 “나와의 채팅에 테스트 메모를 보내 줘.”

처음 접근하는 방의 읽기·전송은 사람이 승인합니다. 읽음 표시는 별도 권한입니다. 확인 창을 지원하지 않는 AI 클라이언트는 패스키 승인 설정이 필요할 수 있습니다.

3. 웹 화면 또는 터미널 사용

웹 화면은 아래 명령을 브라우저를 사용할 컴퓨터에서 실행합니다.

# 같은 컴퓨터에서 실행 중인 데몬 사용
kakao-mcp web

# 서버의 데몬에 SSH로 연결
kakao-mcp web --ssh user@server

터미널에 표시된 http://127.0.0.1:8899/launch?t=... 링크를 브라우저에서 엽니다. 실행 링크는 매번 바뀌며 로그인 권한을 포함하므로 공유하지 마세요. 화면은 실행 링크로 연 탭에서만 동작하므로, 새 탭이나 화면을 다시 시작한 뒤에는 링크를 다시 여세요. 링크 미리보기는 외부 이미지를 불러오지 않고 제목·설명만 보여 줍니다. 데몬 포트가 다르면 --listen 127.0.0.1:포트를 추가합니다.

터미널 명령은 기본적으로 실행한 컴퓨터의 127.0.0.1:8787 데몬을 사용합니다. 원격 서버라면 SSH로 서버에 로그인한 후 실행하세요.

kakao-mcp status                       # 연결 상태
kakao-mcp list                         # 대화방 목록
kakao-mcp chat                         # 터미널 메신저
kakao-mcp history "대화방 이름" 20      # 최근 기록
kakao-mcp send self "테스트 메모"       # 나와의 채팅에 실제 전송
kakao-mcp help                         # 전체 명령 확인

일반 방에서 승인 필요 오류가 나면 안내된 승인 절차를 진행합니다. 전송 결과가 불명확하면 새 요청으로 다시 보내지 말고 기존 requestId의 상태를 확인하세요.

AI가 할 수 있는 일과 승인 범위

이 프로그램은 AI 모델 자체가 아니라 카카오톡 기능을 제공하는 MCP 서버입니다. 요약·답장 작성·일정 판단은 연결한 AI가 수행합니다. 기본 도구 16개, 선택 묶음까지 켜면 총 41개입니다.

ask와 trust 비교

• 나와의 채팅은 기본적으로 읽기·전송·본인 메시지 수정/삭제에 별도 승인이 없습니다. 명시한 읽기 규칙과 운영자 상한은 적용됩니다.

• trust 모드는 기본 읽기·발신뿐 아니라 전달, 수정·삭제, 읽음 표시, 방 나가기·정보 변경, 프로필 변경, 친구 추가·차단·해제도 개별 확인 없이 허용합니다. 방 생성·권한 확대·정지 해제 등은 계속 사람 확인이 필요합니다. 기본값은 ask이며 이번 검사에서 모드를 변경하지 않았습니다.

• ask의 방 전송 허가는 기본 하루 50회이고 trust는 명시하지 않으면 일일 상한이 없습니다. 두 모드 모두 별도 속도 제한은 적용됩니다. 필요한 한도는 운영자가 명시하세요.

• KAKAO_ROOM_CEILING은 허용할 방 ID를 제한합니다. 보안 수정본에서는 본문 열람과 발신에 적용되며, 대화방·친구 목록 전체를 숨기는 기능은 아닙니다. pause는 발신·계정 변경을 멈추는 용도이며 모든 조회·로컬 저장을 차단하는 스위치가 아닙니다.

• MCP 도구로 운영 모드·상한·기능 설정을 임의 변경하거나 서버의 임의 파일·셸을 실행하는 기능은 없습니다. 다만 AI에게 별도의 셸/SSH/파일 도구도 주었다면 그 권한은 별도로 제한해야 합니다.

• 허용된 대화 조회 결과는 AI 클라이언트로 전달됩니다. 외부 모델을 쓰면 그 제공자에게 전달될 수 있으므로 연결한 클라이언트의 데이터 설정을 확인하세요.

4. 선택 도구 묶음과 진단

기본 MCP 도구는 16개입니다. 전체 41개 도구를 노출하려면 서버의 /var/lib/kakao-mcp/app/.env.local에 다음 설정을 추가하거나 기존 값을 수정합니다. 파일 소유자와 비공개 권한을 유지하세요.

KAKAO_MCP_TOOL_GROUPS=chats,friends,events,vault

설정 적용에는 데몬 재시작과 AI 재연결이 필요합니다. 재시작하면 실행 중 일시정지가 해제되므로, 작업 상태를 확인한 뒤 운영자가 실행합니다.

sudo systemctl restart kakao-mcp

도구 노출은 방 접근 권한이나 자동 보관 허용을 대신하지 않습니다. 문제가 생기면 다음 명령으로 확인합니다.

kakao-mcp setup --doctor
systemctl status kakao-mcp --no-pager
sudo journalctl -u kakao-mcp -n 80 --no-pager

인증 정보 복구가 필요하다는 진단이 나오면 서버에서 kakao-mcp setup --repair를 사용합니다. 비밀번호·인증 코드·토큰은 채팅에 붙여 넣지 말고 해당 터미널이나 휴대폰에서 입력하세요.

보안 검사 요약 (2026-11-01, 2026-11-02 추가)

검사 대상은 애플리케이션 소스·격리 테스트·의존성이며 실제 계정과 운영 서버 침투 시험은 포함하지 않았습니다. 확인한 승인 재사용, 방 읽기 상한 우회, 사진 표시 코드 삽입, 링크 미리보기 DNS 재바인딩 문제를 수정한 버전은 0.2.0-rebuild.2입니다. 현재 배포인 0.2.0-rebuild.3에는 이 수정이 포함되어 있습니다.

클라이언트 확인 창은 클라이언트가 사람에게 실제로 물었다는 전제에 의존합니다. AI의 셸/SSH 접근과 사람 승인을 분리해야 한다면 KAKAO_APPROVAL_CLIENT_CONFIRM=off와 패스키 승인을 구성하세요. 패스키가 준비되기 전에 끄면 승인이 필요한 작업이 막힙니다. 같은 OS 사용자나 root의 파일 접근까지 막지는 않습니다.

앱 의존성의 npm audit에서 알려진 취약점은 검사 당시 0건이었습니다. 검사 통과가 모든 보안 문제의 부재를 보장하지는 않습니다. 수정 내용과 운영상 경계는 보안 검사 문서를 참고하세요.

2026-11-02에 레포 전체를 다시 검사해 승인 화면의 대상 방 표시, Linux 접속 사용자 확인, 승인 전 메시지 노출, 웹 화면 세션 보호와 링크 미리보기 표시, CLI 출력의 터미널 제어문자, 일정 추출 지연, 1회 읽기 허가 개수, 첨부 다운로드 크기 문제를 추가로 수정했습니다. 이 수정은 main에 반영되어 있으며 0.2.0-rebuild.3 패키지 파일에는 들어 있지 않으니, 소스에서 새로 npm pack한 패키지를 쓰세요.

소스 개발과 패키지 빌드

git clone https://github.com/ccomajeon/kakao-mcp-demon-ccomajeon.git
cd kakao-mcp-demon-ccomajeon
npm ci
npm test
npm run typecheck
npm run check:package
npm pack

npm pack은 현재 디렉터리에 kakao-mcp-ccomajeon-0.2.0-rebuild.3.tgz를 만듭니다. 생성된 파일을 서버로 옮긴 후 위 1단계의 패키지 설치 명령을 사용하세요. GitHub에서 소스 ZIP/TAR 파일을 받았다면 먼저 압축을 풀고 같은 npm 명령을 실행합니다. 소스 압축본에는 .git이 없고, 관리형 소스 설치는 깨끗한 origin/main 체크아웃만 허용하므로 압축본에서 npm run setup으로 새 서버를 설치하는 방식은 지원되지 않습니다.

이미 실행 중인 데몬에 개발용 클라이언트를 연결할 때는 npm run build --workspace=@kakao-mcp/protocol 후 npm run kakao -- status, npm run kakao -- chat, npm run web을 사용할 수 있습니다.

검증 상태와 지원 범위

2026-11-02 보안 수정 반영 후 Linux(Node 22) 컨테이너에서 측정한 결과이며 npm run typecheck와 npm run check:package도 통과했습니다. 건너뛴 검사는 실행 환경이 맞지 않아 자동으로 빠진 것으로, systemd 격리, 실제 서비스 계정 설치, SSH 대상 연결, Windows 전용 동작 등이 포함됩니다.

현재 버전은 npm 레지스트리에 게시하지 않았습니다. 위에 안내한 로컬 .tgz 파일로 설치합니다.

GitHub Actions는 단위·타입·패키지·공개 파일 검사를 실행합니다. KAKAO_MCP_DENYLIST 저장소 Secret을 설정하면 비공개 금지어 목록도 검사하며, 미설정 시 공개 패턴만 검사합니다. npm 게시 워크플로는 별도 환경 승인·trusted publishing 구성이 필요하며 소스 업로드만으로 npm에 게시되지 않습니다.

더 읽을거리

라이선스

MIT 라이선스입니다. 자세한 내용은 LICENSE를 참고하세요.

Kakao의 공식 제품이 아니며 Kakao와 제휴하거나 승인을 받은 프로젝트가 아닙니다. KakaoTalk 및 관련 상표의 권리는 각 권리자에게 있습니다.