​
What is MCP (Model Context Protocol)

Model Context Protocol (MCP) is a standardized interface that allows AI models like Claude and GPT to interact with external services and tools. It provides a structured way for AI assistants to execute actions, access data, and control applications through predefined functions and commands. In the context of Periskope WhatsApp, MCP enables AI assistants to directly manage WhatsApp conversations, send messages, handle contacts, and perform other WhatsApp-related operations programmatically.

​
Setup

1

Connect WhatsApp

  1. Sign up for an account at console.periskope.app
  2. You will need a phone number that you will use to manage all your WhatsApp chats, groups and communities logged in on WhatsApp.
  3. Open Settings on your WhatsApp App and click on Link device
  4. Now scan the QR code shown on Periskope screen
If you face any errors, click on refetch QR to fetch a new QR code.
2

Verify Connection

Once you’re successfully connected to WhatsApp, you will see the phone syncing screen on Periskope.After the sync is performed, you’ll be able to see the metrics and chats on Periskope.
To perform any action regarding your phone (such as restart, resync, delete), you can visit here. To add more phones, you can visit here.
3

Install Prerequisites

Ensure you have the following installed:
  • Node.js v17 or higher (Install from nodejs.org)
  • A Periskope account
  • An MCP client (Claude Desktop, Cursor etc.)
4

Configure MCP

  1. Navigate to Settings > MCP in your console
Step 1

MCP settings

  1. Generate a new API key
5

Install MCP Package

Open a terminal and install the MCP package globally:
npm install -g @periskope/whatsapp-mcp
6

Setup Configuration

  1. Select an API key from the list and copy the entire JSON configuration
  2. Add the copied configuration to your mcp.json file (typically located at ~/.cursor/mcp.json). The configuration should look similar to this:
For MacOS
{
  "mcpServers": {
    "periskope-mcp": {
      "command": "npx",
      "args": ["-y", "@periskope/whatsapp-mcp"],
      "env": {
        "PERISKOPE_API_KEY": "your_periskope_api_key_here",
        "PERISKOPE_PHONE_ID": "your_periskope_phone_id_here"
      }
    }
  }
}
For Windows
{
  "mcpServers": {
    "periskope-mcp": {
      "command": "cmd",
      "args": ["/k", "npx", "-y", "@periskope/whatsapp-mcp"],
      "env": {
        "PERISKOPE_API_KEY": "your_periskope_api_key_here",
        "PERISKOPE_PHONE_ID": "your_periskope_phone_id_here"
      }
    }
  }
}

​
MCP Client Integration

Claude Desktop Setup Guide

View Setup Guide →

Cursor MCP Setup

View Documentation →

​
Available Tools

The MCP provides several tools for interacting with Periskope’s WhatsApp API:

​
Chat Management

  • periskope_list_chats: Lists all WhatsApp chats
  • periskope_get_chat: Gets details about a specific WhatsApp chat
  • periskope_create_chat: Creates a new WhatsApp group chat
  • periskope_update_chat_labels: Updates the labels of a WhatsApp chat
  • periskope_update_chat: Updates a WhatsApp chat properties on periskope
  • periskope_update_chat_settings: Updates the settings of a WhatsApp chat
  • periskope_search_chat: Searches for chats by name

​
Message Management

  • periskope_send_message: Sends a WhatsApp message to a specified number
  • periskope_list_messages_in_a_chat: Lists all messages in a specific WhatsApp chat
  • periskope_get_message_by_id: Gets a message by its ID
  • periskope_react_to_message: Reacts to a message
  • periskope_forward_message: Forwards a message to other chats
  • periskope_edit_message: Edits a message in a chat
  • periskope_delete_message: Deletes a message from a chat
  • periskope_search_message: Searches for messages by content

​
Contact Management

  • periskope_list_contacts: Lists all WhatsApp contacts
  • periskope_update_contact_labels: Updates the labels of a WhatsApp contact
  • periskope_update_contact: Updates a WhatsApp contact
  • periskope_get_contact_by_id: Gets a contact by its ID
  • periskope_search_contact: Searches for contacts by name

​
Group Management

  • periskope_add_participants_to_group: Adds participants to a WhatsApp group
  • periskope_remove_participants_from_group: Removes participants from a WhatsApp group
  • periskope_promote_participants_to_admins: Promotes participants to admins in a WhatsApp group
  • periskope_demote_participants_from_admins: Demotes participants from admins in a WhatsApp group

​
Ticket Management

  • periskope_get_all_tickets: Gets all tickets
  • periskope_get_ticket: Gets details about a specific ticket
  • periskope_update_ticket: Updates an existing ticket

​
Use Cases

Ticket Management

Close, reopen, reassign, and update tickets directly through natural language. Set priorities, add labels, update status, and manage ticket properties effortlessly.
“Close all tickets assigned to John and reassign them to Sarah with high priority”

Message Operations

Send, search, forward, and delete messages on WhatsApp with simple commands. Search message history, bulk forward content, and manage message reactions all through conversation.
“Search for messages containing ‘invoice’ in the last week and forward them to the accounting group”

Chat Management

Create and update chats, manage group settings, and handle chat properties. Set descriptions, images, and control messaging permissions through natural language.
“Create a new group called ‘Project Alpha’ with Bob, Alice, and Charlie, and set it to admin-only messages”

Group Administration

Add, remove, demote, and promote group participants with ease. Manage admin privileges and participant access through simple commands.
“Add the new interns to the ‘Marketing Team’ group and promote Sarah to admin”

Contact Management

Search, update, and manage contact information efficiently. Add labels, update contact properties, and organize your WhatsApp contacts through conversation.
“Find all contacts labeled as ‘VIP’ and update their custom properties to include their company names”