WhatsApp MCP 서버

FastMCP를 사용하여 WhatsApp Business API와 상호 작용할 수 있는 MCP(Model Context Protocol) 인터페이스를 제공하는 서버입니다.

소개

WhatsApp MCP 서버는 Claude와 같은 언어 모델이 GreenAPI를 통해 WhatsApp 기능과 상호 작용할 수 있도록 하는 Python 구현입니다. FastMCP를 활용하여 성능 향상, 개발자 경험 개선, 그리고 더욱 깔끔한 구현을 제공합니다.

Related MCP server: MCP Evolution API

특징

메시징 : WhatsApp 연락처로 문자 메시지 보내기
그룹 관리 : 그룹 생성, 회원 목록, 참가자 추가/제거
세션 처리 : WhatsApp API 세션 관리
채팅 기록 : 채팅 목록 및 메시지 기록 검색

WhatsApp API 클라이언트

이 프로젝트는 WhatsApp과 상호 작용하기 위해 whatsapp-api-client-python 라이브러리를 사용합니다. 클라이언트는 WhatsApp Cloud API에 대한 액세스를 제공하며, 사용하려면 GreenAPI 계정이 필요합니다.

환경 변수

이 프로젝트는 구성을 위해 환경 변수를 사용합니다.

GREENAPI_ID_INSTANCE : GreenAPI ID 인스턴스
GREENAPI_API_TOKEN : GreenAPI API 토큰

이러한 설정은 사용자 환경에서 설정할 수도 있고, 제공된 .env 파일을 사용할 수도 있습니다(설치 지침 참조).

설치

지엑스피1

용법

MCP 서버를 실행합니다.

# Run the MCP server on default host (127.0.0.1) and port (8000)
whatsapp-mcp

# Specify host and port
whatsapp-mcp --host 0.0.0.0 --port 9000

디버깅을 위해:

whatsapp-mcp --debug

서버는 MCP(Model Context Protocol)를 사용하여 통신하며 FastMCP로 실행하는 경우 HTTP 또는 WebSockets를 통해 액세스할 수 있습니다.

사용 가능한 도구

open_session : 새로운 WhatsApp 세션을 엽니다
send_message : 채팅방에 메시지 보내기
get_chats : 채팅 목록을 가져옵니다
create_group : 새로운 WhatsApp 그룹을 만듭니다
get_group_participants : 그룹 참가자를 가져옵니다

FastMCP API 참조

WhatsApp MCP 서버는 FastMCP를 사용하여 WebSocket과 HTTP 엔드포인트를 모두 제공합니다.

웹소켓: ws://localhost:8000/mcp
HTTP: http://localhost:8000/mcp

curl과 같은 도구를 사용하여 API를 직접 테스트할 수 있습니다.

# List available tools
curl -X POST http://localhost:8000/mcp/listTools

# Call a tool
curl -X POST http://localhost:8000/mcp/callTool \
  -H "Content-Type: application/json" \
  -d '{"name": "open_session", "arguments": {}}'

Claude Code에 추가하는 방법

Claude에 WhatsApp 서버를 추가하려면 claude mcp add 명령을 사용하세요.

# Add the WhatsApp MCP server
$ claude mcp add whatsapp -- whatsapp-mcp

# List existing MCP servers - Validate that the server is running
claude mcp list

# Start claude code
claude

Claude와 함께 사용

WhatsApp MCP 서버가 실행되면 대화에서 Claude를 사용하여 해당 서버와 상호 작용할 수 있습니다.

WhatsApp으로 인증하기

Login to WhatsApp

메시지 보내기

Send the "Hello" message to John Doe

Claude Desktop과 함께 사용

Claude Desktop에서 WhatsApp MCP 서버를 사용하려면 claude_desktop_config.json 파일에 이를 추가해야 합니다.

pip 설치 사용(권장)

"mcpServers": {
  "whatsapp": {
    "command": "python",
    "args": ["-m", "whatsapp_mcp"]
  }
}

실행 파일을 사용하여

"mcpServers": {
  "whatsapp": {
    "command": "whatsapp-mcp"
  }
}

Docker 사용

"mcpServers": {
  "whatsapp": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "GREENAPI_ID_INSTANCE=your_instance_id", "-e", "GREENAPI_API_TOKEN=your_api_token", "whatsapp-mcp-server"]
  }
}

Claude Desktop을 시작하기 전에 GreenAPI 자격 증명을 환경 변수나 .env 파일로 설정하는 것을 잊지 마세요.

명령줄 옵션

WhatsApp MCP 서버는 다음 명령줄 인수를 허용합니다.

--debug : 디버깅을 위한 자세한 정보 표시 수준을 높입니다.
--host : 서버를 바인딩할 호스트(기본값: 127.0.0.1)
--port : 서버를 바인딩할 포트(기본값: 8000)

디버깅

MCP 서버 디버깅을 위해:

MCP 검사기를 사용하세요: npx @modelcontextprotocol/inspector whatsapp-mcp
Claude Desktop 로그 디렉토리(일반적으로 macOS에서는 ~/Library/Logs/Claude/ )에서 로그를 확인합니다.
대화형 API 설명서를 보려면 http://localhost:8000 에서 FastMCP 웹 인터페이스에 액세스하세요.

개발

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
flake8 src/

# Run type checking
mypy src/

이 프로젝트는 다음을 포함하는 최신 pyproject.toml 구성을 사용합니다.

애플리케이션을 실행하는 데 필요한 핵심 종속성
pip install -e ".[dev]" 사용하면 개발 종속성을 사용할 수 있습니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

WhatsApp MCP Server