Skip to main content

​
Features

  • Send Messages: Agents can send text messages to any phone number.
  • Session Management: Create, login, and manage multiple WhatsApp sessions.
  • QR Code Login: Authenticate via QR code scanning.
  • Headless Operation: Runs in headless mode for server environments.

​
Setup

​
Prerequisites

  1. Chrome Browser: Google Chrome must be installed on the server.
  2. ChromeDriver: The correct version of ChromeDriver for your Chrome installation. The system attempts to install/find it automatically.
  3. Dependencies: 
    pip install selenium webdriver-manager fastmcp

​
Usage

​
Session Management

The integration manages “sessions”, where each session corresponds to a WhatsApp Web instance.
  1. Create/Login Session: Agents can initiate a login which will generate a QR code (if not already logged in).
  2. QR Code: The QR code is extracted from the headless browser and can be returned to the user/agent for scanning.

​
Available Tools

The MCP server exposes the following tools:

​
login_whatsapp_session

Initiates a login for a session. If not logged in, it returns a QR code.
  • Arguments:
    • session_id (string): Unique identifier for the session (e.g., agent ID).

​
check_whatsapp_login_status

Checks if a session is successfully logged in.
  • Arguments:
    • session_id (string): The session ID.

​
send_whatsapp_message

Sends a message to a specific phone number.
  • Arguments:
    • session_id (string): The authenticated session ID.
    • phone_number (string): The recipient’s phone number (with country code).
    • message (string): The text message to send.

​
close_whatsapp_session

Closes and cleans up a session.
  • Arguments:
    • session_id (string): The session ID to close.

​
REST API

The server also exposes REST endpoints for session management:
  • GET /sessions/{session_id}/login: Initiate login.
  • GET /sessions/{session_id}/login-status: Check status.

​
Architecture

The integration uses selenium to control a headless Chrome instance.
  • Session Data: Chrome user profiles are stored in ./chrome_profiles/{session_id} to persist logins.
  • Database: Session metadata is stored in a local SQLite database (sessions.db).
  • MCP: fastmcp is used to expose the automation logic as tools for agents.

​
Key Files

  • mcp_server.py: Main server logic, Selenium automation, and tool definitions.
  • database.py: Local database management for session metadata.