Evolution API MCP

Evolution API(오픈 소스, 자체 호스팅)를 사용하여 Claude Code에서 직접 WhatsApp 메시지를 송수신하기 위한 MCP 서버입니다.

주요 기능

• WhatsApp 인스턴스 생성 및 관리

• 텍스트, 미디어, 오디오, 위치, 연락처, 설문조사, 스티커, 버튼 및 목록 메시지 전송

• 대화 및 수신 메시지 읽기

• 메시지 반응, 채팅 보관, 읽음 처리

Related MCP server: mcp-evolution

사전 요구 사항

• Docker Desktop

• Python 3.11+

• uv (Python 패키지 관리자)

• Claude Code

설치 방법

1. Evolution API 실행

git clone https://github.com/SEU_USUARIO/evolution-api-mcp.git
cd evolution-api-mcp
docker compose up -d

약 15초 정도 기다린 후 테스트합니다:

curl http://localhost:8080/

{"status":200,"message":"Welcome to the Evolution API, it is working!"}가 반환되어야 합니다.

2. MCP 서버 설치

uv venv
uv pip install -e .

3. Claude Code에 등록

claude mcp add evolution-api -s user -- evolution-api-mcp

또는 ~/.claude.json 파일에 수동으로 추가합니다:

{
  "mcpServers": {
    "evolution-api": {
      "type": "stdio",
      "command": "evolution-api-mcp",
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "evo_mcp_2024"
      }
    }
  }
}

Windows: command는 .exe의 전체 경로여야 할 수 있습니다: C:/Users/사용자명/evolution-api-mcp/.venv/Scripts/evolution-api-mcp.exe

4. WhatsApp 연결

1. 브라우저에서 http://localhost:8080/manager/ 를 엽니다.

2. Global API Key를 사용합니다: evo_mcp_2024

3. 인스턴스를 생성합니다 (예: "meuwhats")

4. "QR 코드 생성"을 클릭합니다.

5. WhatsApp으로 스캔합니다: 설정 > 연결된 기기 > 기기 연결

5. 사용하기!

Claude Code를 다시 열고 사용을 시작하세요:

> envia uma mensagem pro 5511999999999 dizendo oi
> mostra minhas conversas recentes
> envia uma foto pra fulano

설정

Docker Compose의 기본 API 키는 evo_mcp_2024입니다. 원할 경우 docker-compose.yml에서 변경하세요.

구조

evolution-api-mcp/
├── docker-compose.yml          # Evolution API + PostgreSQL
├── pyproject.toml               # Dependencias Python
└── src/evolution_api_mcp/
    ├── server.py                # MCP server (FastMCP + CodeMode)
    ├── client.py                # HTTP client async
    └── tools/
        ├── instance.py          # Criar/conectar/deletar instancias
        ├── messages.py          # Enviar texto, midia, audio, etc.
        └── chat.py              # Listar chats, ler mensagens

사용 가능한 도구

인스턴스 (Instance)

• create_instance - WhatsApp 인스턴스 생성

• connect_instance - 연결 및 QR 코드 생성

• fetch_instances - 인스턴스 목록 조회

• connection_state - 연결 상태 확인

• logout_instance - WhatsApp 로그아웃

• restart_instance - 인스턴스 재시작

• delete_instance - 인스턴스 삭제

메시지 (Messages)

• send_text - 텍스트 전송

• send_media - 이미지, 비디오 또는 문서 전송

• send_audio - 오디오/음성 메시지 전송

• send_location - 위치 전송

• send_contact - 연락처 카드 전송

• send_reaction - 이모지 반응 전송

• send_poll - 설문조사 전송

• send_buttons - 대화형 버튼 전송

• send_list - 대화형 목록 전송

• send_sticker - 스티커 전송

채팅 (Chat)

• find_chats - 대화 목록 조회

• find_messages - 채팅 메시지 읽기

• archive_chat - 채팅 보관/보관 해제

• mark_message_as_read - 읽음 처리

라이선스

MIT