> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsapi.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Bring WhatsApp automation to any MCP-compatible AI assistant

The WSAPI MCP Server exposes **60+ WSAPI-powered tools** to any Model Context Protocol (MCP) compatible assistant, letting LLMs send messages, manage contacts and groups, and administer WhatsApp instances without leaving the conversation.

## What you get

* Full coverage for messaging, contact, group, chat, session, instance, and account operations
* Secure credential handling with runtime validation via Zod schemas
* Built-in health check, structured logging, and graceful shutdown helpers
* Drop-in compatibility with Claude Desktop and other MCP clients

## Requirements

* Node.js 18 or later
* npm 9 or later
* Active WSAPI subscription with a paired instance
* WSAPI API key and instance ID

## Installation

<Tabs>
  <Tab title="npx (Recommended)">
    ```bash theme={null}
    WSAPI_API_KEY=your_api_key \
    WSAPI_INSTANCE_ID=your_instance_id \
    npx @wsapichat/mcp-server
    ```
  </Tab>

  <Tab title="Global install">
    ```bash theme={null}
    npm install -g @wsapichat/mcp-server

    WSAPI_API_KEY=your_api_key \
    WSAPI_INSTANCE_ID=your_instance_id \
    wsapi-mcp
    ```
  </Tab>

  <Tab title="Project dependency">
    ```bash theme={null}
    npm install @wsapichat/mcp-server

    WSAPI_API_KEY=your_api_key \
    WSAPI_INSTANCE_ID=your_instance_id \
    npx wsapi-mcp
    ```
  </Tab>
</Tabs>

## Environment variables

| Variable               | Required | Description                         | Default                  |
| ---------------------- | -------- | ----------------------------------- | ------------------------ |
| `WSAPI_API_KEY`        | Yes      | WSAPI API key for authentication    | —                        |
| `WSAPI_INSTANCE_ID`    | Yes      | WhatsApp instance to control        | —                        |
| `WSAPI_BASE_URL`       | No       | Custom API endpoint                 | `https://api.wsapi.chat` |
| `WSAPI_TIMEOUT`        | No       | HTTP timeout in milliseconds        | `30000`                  |
| `WSAPI_RETRY_ATTEMPTS` | No       | Retries for recoverable errors      | `3`                      |
| `WSAPI_RETRY_DELAY`    | No       | Milliseconds between retries        | `1000`                   |
| `LOG_LEVEL`            | No       | `error`, `warn`, `info`, or `debug` | `info`                   |

## Connect to Claude Desktop

Add the server to your Claude Desktop config file:

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "wsapi": {
          "command": "npx",
          "args": ["@wsapichat/mcp-server"],
          "env": {
            "WSAPI_API_KEY": "your_api_key_here",
            "WSAPI_INSTANCE_ID": "your_instance_id_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "wsapi": {
          "command": "npx",
          "args": ["@wsapichat/mcp-server"],
          "env": {
            "WSAPI_API_KEY": "your_api_key_here",
            "WSAPI_INSTANCE_ID": "your_instance_id_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  For a global install, replace `"command": "npx"` and `"args"` with `"command": "wsapi-mcp"`.
</Note>

## Tool catalog

The server registers every tool exposed by WSAPI:

| Category      | Tools                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Messaging** | `whatsapp_send_text`, `whatsapp_send_media`, `whatsapp_send_document`, `whatsapp_send_sticker`, `whatsapp_send_location`, `whatsapp_send_reaction`, `whatsapp_edit_message`, `whatsapp_delete_message` |
| **Contacts**  | `whatsapp_get_contacts`, `whatsapp_get_contact`, `whatsapp_create_contact`, `whatsapp_update_contact`, `whatsapp_get_contact_picture`, `whatsapp_subscribe_contact_presence`                           |
| **Groups**    | `whatsapp_get_groups`, `whatsapp_create_group`, `whatsapp_update_group_name`, `whatsapp_manage_participants`                                                                                           |
| **Chats**     | `whatsapp_get_chats`, `whatsapp_get_chat`, `whatsapp_set_chat_presence`, `whatsapp_archive_chat`, `whatsapp_pin_chat`                                                                                  |
| **Session**   | `whatsapp_get_session_status`, `whatsapp_get_qr_code`, `whatsapp_get_pair_code`, `whatsapp_logout`                                                                                                     |
| **Instance**  | `whatsapp_get_instance_settings`, `whatsapp_update_instance_settings`, `whatsapp_restart_instance`, `whatsapp_update_api_key`                                                                          |
| **Account**   | `whatsapp_get_account_info`, `whatsapp_set_account_name`, `whatsapp_set_account_picture`, `whatsapp_set_account_presence`, `whatsapp_set_account_status`                                               |

## Common workflows

* **Verify connectivity** — call `list_tools` in your MCP client and confirm the WSAPI catalog is returned
* **Send a message** — use `whatsapp_send_text` with `to` and `message` fields
* **Share media** — use `whatsapp_send_media` with Base64 payload and MIME type
* **Manage sessions** — use `whatsapp_get_qr_code` or `whatsapp_get_pair_code` when the phone link expires

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failures">
    Double-check your API key, instance status, and environment variable spelling. The startup validator prints specific missing keys.
  </Accordion>

  <Accordion title="Timeouts or flaky delivery">
    Increase `WSAPI_TIMEOUT`, `WSAPI_RETRY_ATTEMPTS`, or `WSAPI_RETRY_DELAY` for congested networks.
  </Accordion>

  <Accordion title="Claude Desktop can't see the server">
    Ensure the server runs in the same user session, verify the config path for your OS, and restart Claude after edits.
  </Accordion>

  <Accordion title="Need more context?">
    Set `LOG_LEVEL=debug` to dump request/response metadata (media payloads remain redacted).
  </Accordion>
</AccordionGroup>

## GitHub

[github.com/wsapi-chat/wsapi-mcp](https://github.com/wsapi-chat/wsapi-mcp)