Skip to main content
Glama
ekaksher
by ekaksher

WhatsApp MCP Server

A local Python MCP server that automates WhatsApp Web through Playwright and exposes a small set of WhatsApp tools over stdio.

What this project does

  • Runs as an MCP server over stdio.

  • Uses Python instead of Node.

  • Uses Playwright with Chromium.

  • Persists the WhatsApp Web session under ./data/profile.

Related MCP server: MCP Playwright Server

Current tools

  • get_auth_status

  • wait_until_ready

  • list_recent_chats

  • send_message

  • get_recent_messages

  • shutdown_browser

send_message and get_recent_messages accept either phone_number or chat_name. chat_name works by searching the existing WhatsApp sidebar/chat list. For larger get_recent_messages requests, the server attempts to scroll upward and load older visible history before extracting messages.

Important limitations

  • This project automates WhatsApp Web, not the official WhatsApp Business API.

  • WhatsApp Web markup changes regularly, so selectors may need maintenance.

  • You should use a dedicated account and review WhatsApp's terms before production use.

  • The repository is initialized as a Git repository on the main branch.

  1. Copy the environment file:

cp .env.example .env
  1. Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
  1. Install dependencies:

pip install -r requirements.txt
python3 -m playwright install chromium
  1. For local login, set WHATSAPP_HEADLESS=false in .env.

  2. Start the server locally:

PYTHONPATH=src python3 -m whatsapp_mcp.main
  1. From your MCP client, call get_auth_status.

  2. If a browser window opens, scan the QR code directly in that window.

  3. Call wait_until_ready.

Example MCP client configuration

For Claude Desktop or another MCP client, local Python execution is the recommended configuration.

{
  "mcpServers": {
    "whatsapp": {
      "command": "/absolute/path/to/project/.venv/bin/python3",
      "args": [
        "-m",
        "whatsapp_mcp.main"
      ],
      "cwd": "/absolute/path/to/project",
      "env": {
        "PYTHONPATH": "/absolute/path/to/project/src",
        "WHATSAPP_HEADLESS": "false",
        "WHATSAPP_PROFILE_DIR": "/absolute/path/to/project/data/profile"
      }
    }
  }
}

Tool examples

get_auth_status

{
  "name": "get_auth_status",
  "arguments": {}
}

send_message

{
  "name": "send_message",
  "arguments": {
    "chat_name": "John Appleseed",
    "text": "Hello from the WhatsApp MCP server"
  }
}

get_recent_messages

{
  "name": "get_recent_messages",
  "arguments": {
    "chat_name": "John Appleseed",
    "count": 10
  }
}

Project structure

.
├── docs/
├── src/whatsapp_mcp/
├── .env.example
└── pyproject.toml

Documentation

Available Tools

6 tools
get_auth_statusB

Open WhatsApp Web if needed and report whether login is complete.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool may open WhatsApp Web and reports login status, but lacks details on behavioral traits such as side effects (e.g., browser automation, potential delays), error handling, or what 'report' entails. For a tool with no annotations, this is insufficient to fully inform an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words. It is front-loaded with the core action and condition, making it easy to parse. Every part of the sentence earns its place by specifying the tool's behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no annotations, and no output schema, the description provides basic context but lacks completeness. It doesn't explain what the output looks like (e.g., boolean status, detailed report) or potential errors. For a tool that interacts with external systems like WhatsApp Web, more detail on behavior and results would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add parameter semantics, but that's acceptable here. A baseline of 4 is appropriate since the schema fully covers the absence of parameters, and the description doesn't need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Open WhatsApp Web if needed and report whether login is complete.' It specifies the action (open WhatsApp Web conditionally and report login status) and the resource (WhatsApp Web). However, it doesn't explicitly differentiate from sibling tools like 'wait_until_ready' which might also involve readiness checks, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context: use this tool to check login status, possibly before other operations. It suggests a conditional action ('if needed'), but doesn't provide explicit guidance on when to use it versus alternatives like 'wait_until_ready' or prerequisites for other tools like 'send_message'. The guidance is present but not comprehensive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recent_messagesC

Read recent messages from a chat identified by either a phone number or a chat name.

ParametersJSON Schema
NameRequiredDescriptionDefault
phone_numberNo
chat_nameNo
limitNo
countNoAlias for limit.

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but provides minimal behavioral context. It states 'Read' (implying read-only) but doesn't disclose rate limits, pagination, error conditions, or what 'recent' means temporally. No contradictions exist, but critical behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. However, it could be more structured by separating identification methods from the action, and it lacks necessary details that would justify additional sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, low schema coverage, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or behavioral constraints, making it inadequate for a tool with 4 parameters and read operations in a chat context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (25%), with only 'count' having a description ('Alias for limit'). The description adds that phone_number or chat_name identify the chat, but doesn't explain format, exclusivity, or default behavior. It fails to compensate for the coverage gap, leaving most parameters semantically unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read recent messages') and resource ('from a chat'), specifying identification by phone number or chat name. It distinguishes from siblings like 'send_message' (write vs read) and 'list_recent_chats' (messages vs chats), but doesn't explicitly differentiate from other read operations if they existed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., authentication status from 'get_auth_status'), when to prefer phone_number vs chat_name, or how it relates to 'list_recent_chats' for discovering chats first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recent_chatsC

List the most recent chats visible in WhatsApp Web.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While it implies a read-only operation ('List'), it doesn't specify whether this requires authentication, what happens if WhatsApp Web isn't loaded, whether there are rate limits, or what format the output takes. The description provides minimal behavioral context beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a simple tool and gets straight to the point with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations, no output schema, and incomplete parameter documentation, the description is insufficient. It doesn't explain what 'recent' means, how results are ordered, what data is returned, or any error conditions. Given the complexity of interacting with WhatsApp Web, more context is needed for an agent to use this effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. However, the description mentions no parameters at all, while the schema shows one optional 'limit' parameter. The description doesn't add any parameter semantics beyond what's already in the schema structure. Baseline 3 is appropriate since the schema provides the parameter definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and resource ('most recent chats visible in WhatsApp Web'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling 'get_recent_messages', which could be confusing for an agent trying to choose between them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_recent_messages' or 'get_auth_status'. There's no mention of prerequisites (like needing authentication), nor any context about what 'recent' means or how this differs from other chat-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_messageC

Send a WhatsApp message using either a phone number or an existing chat name.

ParametersJSON Schema
NameRequiredDescriptionDefault
phone_numberNoRecipient phone number in international or local format.
chat_nameNoVisible WhatsApp chat name to open from the sidebar search.
textYesMessage body to send.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the action is 'send' (implying a write operation) but doesn't cover critical aspects like authentication requirements, rate limits, error conditions, or what happens if both phone_number and chat_name are provided. This leaves significant gaps for agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a straightforward messaging tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write operation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, return values, error handling, or important behavioral constraints. The agent lacks critical information needed to use this tool effectively in context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value by mentioning the two recipient options (phone number or chat name) but doesn't provide additional syntax, format details, or usage context beyond what's in the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Send a WhatsApp message') and resource ('WhatsApp message'), specifying it can use either a phone number or chat name. However, it doesn't differentiate from sibling tools like 'get_recent_messages' or 'list_recent_chats' beyond the basic verb difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the two recipient options (phone number or chat name) but provides no guidance on when to choose one over the other, prerequisites for sending messages, or when to use this versus other messaging-related tools. No explicit alternatives or exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shutdown_browserA

Close the browser context and stop the WhatsApp automation session.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses the behavioral outcome (closing browser and stopping automation), which is appropriate for a destructive operation. However, it doesn't mention whether this is reversible, what happens to unsaved data, or authentication implications, leaving some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and consequence, making it immediately clear what the tool does without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive operation with no annotations and no output schema, the description provides the essential purpose but lacks details about side effects, confirmation requirements, or what happens after shutdown. Given the complexity of terminating an automation session, more context about consequences would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters and 100% schema coverage, the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and doesn't need to compensate for any schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Close the browser context and stop the WhatsApp automation session'), which includes both the immediate effect (closing browser) and broader consequence (stopping automation). It distinguishes from sibling tools like 'get_auth_status' or 'send_message' by being the only termination operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (when ending an automation session), but doesn't explicitly state when to use this vs alternatives like 'wait_until_ready' or prerequisites. It's clear this should be used to terminate the session, but lacks explicit exclusions or comparison to other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

wait_until_readyB

Wait until WhatsApp Web is fully authenticated and ready for use.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeout_secondsNo

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions waiting for authentication and readiness, which implies this is a blocking operation, but it doesn't detail what 'fully authenticated and ready' entails (e.g., UI loaded, contacts synced), potential timeouts, error handling, or side effects. This leaves significant gaps in understanding the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with zero wasted words—it directly states the tool's purpose without redundancy. It's appropriately sized and front-loaded, making it easy to grasp immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a blocking wait operation with no annotations, no output schema, and minimal parameter documentation), the description is incomplete. It doesn't explain what 'ready for use' means, what happens on timeout or failure, or what the agent should expect after invocation, leaving key contextual gaps for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter ('timeout_seconds') with 0% description coverage, so the schema provides no semantic context. The description doesn't mention parameters at all, but since there's only one parameter and its purpose (timeout) is inferable from the name and schema constraints, the lack of explicit parameter info is less critical. However, it doesn't add meaning beyond what's minimally deducible.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Wait until') and the target state ('WhatsApp Web is fully authenticated and ready for use'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_auth_status' (which checks status rather than waits), leaving room for slight ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when WhatsApp Web needs to be authenticated and ready, but it doesn't provide explicit guidance on when to use this versus alternatives like 'get_auth_status' (for checking status without waiting) or prerequisites (e.g., after launching the browser). It offers some context but lacks clear exclusions or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: authentication status, message retrieval, chat listing, message sending, session shutdown, and readiness waiting. The descriptions make it unambiguous which tool to use for each task.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (e.g., get_auth_status, send_message, shutdown_browser) with snake_case throughout. The naming is predictable and readable across all six tools.

Tool Count5/5

Six tools is well-scoped for a WhatsApp automation server, covering core operations like authentication, messaging, chat management, and session control without being too sparse or bloated. Each tool earns its place in the workflow.

Completeness4/5

The toolset covers essential WhatsApp Web operations (authentication, messaging, chat listing) and session lifecycle (shutdown, readiness). Minor gaps might include advanced features like media handling or group management, but core workflows are well-supported.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ekaksher/whatsapp-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server