Skip to main content

​
Overview

Use the WaLead API as MCP tools inside Cursor, Claude Desktop, or any MCP client. The same endpoints (campaigns, leads, conversations, embed) are exposed as tools so the AI can list campaigns, add leads, read/send messages, or create an embed link-account URL.

​
Download

Download Walead MCP Package

Download the latest MCP package (walead-mcp-v1.0.0.zip) to get started
Package contents:
  • Pre-built MCP server
  • Installation guide
  • Configuration examples
  • Quick start instructions
The MCP package is a standalone distribution. You don’t need access to the walead-api-rest repository.

​
Installation

​
1. Download and Extract

Download the MCP package using the download button above, or directly from: 
https://github.com/sergi-waLead/walead-documentation/releases/download/1.0.0/walead-mcp-v1.0.0.zip
Extract the ZIP to your preferred location:
  • Windows: C:\walead-mcp
  • Mac/Linux: ~/walead-mcp

​
2. Install Dependencies

Open a terminal in the extracted folder and run: 
cd /path/to/walead-mcp
npm install

​
3. Get Your API Key

  1. Go to app.walead.ai
  2. Navigate to Settings → API & Integrations
  3. Copy your API key (or generate a new one)

​
Configuration

​
For Cursor

Edit your Cursor MCP configuration file:
  • Windows: %USERPROFILE%\.cursor\mcp.json
  • Mac: ~/.cursor/mcp.json
  • Linux: ~/.cursor/mcp.json
Add the following configuration: 
{
  "mcpServers": {
    "walead": {
      "command": "node",
      "args": ["/absolute/path/to/walead-mcp/dist/index.js"],
      "env": {
        "WALEAD_API_URL": "https://app-api.walead.ai",
        "WALEAD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
Important:
  • Replace /absolute/path/to/walead-mcp with the actual path where you extracted the package
  • On Windows, use double backslashes: C:\\walead-mcp\\dist\\index.js
  • Replace YOUR_API_KEY with your actual API key from step 3
Restart Cursor completely for the changes to take effect.

​
For Claude Desktop

Edit the Claude Desktop configuration file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
Add the same configuration as Cursor: 
{
  "mcpServers": {
    "walead": {
      "command": "node",
      "args": ["/absolute/path/to/walead-mcp/dist/index.js"],
      "env": {
        "WALEAD_API_URL": "https://app-api.walead.ai",
        "WALEAD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
Restart Claude Desktop for the changes to take effect.

​
Tools exposed

ToolDescription
walead_list_campaignsList campaigns (optional: status, search)
walead_get_campaignGet one campaign by ID
walead_create_campaignCreate campaign (name)
walead_add_leadsAdd leads to a campaign (leads or linkedinUrls)
walead_list_conversationsList unibox conversations
walead_get_conversationGet one conversation with messages
walead_send_messageSend message in a conversation
walead_mark_conversation_readMark conversation as read
walead_create_embed_link_account_sessionCreate embed URL for link-account iframe (optional returnUrl)

​
Use Cases

  • AI-powered campaign management: Ask AI to create campaigns, add leads, and monitor progress
  • Automated conversation handling: Let AI read and respond to LinkedIn messages
  • Smart lead enrichment: AI can analyze conversations and update lead data
  • Dynamic reporting: Ask AI to fetch analytics and generate insights

​
Example Prompts

Once configured, you can use natural language in Cursor or Claude Desktop:
  • “List all active campaigns in my WaLead workspace”
  • “Add these 10 LinkedIn URLs to campaign XYZ”
  • “Show me unread conversations from the last week”
  • “Send a follow-up message to conversation ABC123”
  • “Create an embed session for linking a LinkedIn account”

​
Verification

After configuring and restarting your IDE, verify the MCP is working:
  1. Open Chat in Cursor (Ctrl+L or Cmd+L) or Claude Desktop
  2. Type: “List my Walead campaigns”
  3. The AI should use the walead_list_campaigns tool and show your campaigns
If it works, you’re all set! 🎉

​
Troubleshooting

​
MCP not recognized

Issue: Cursor/Claude doesn’t recognize Walead tools Solutions:
  • Verify the mcp.json file is in the correct location
  • Check that the JSON is valid (no syntax errors)
  • Ensure you’ve restarted the IDE completely
  • Check the path to dist/index.js is absolute and correct

​
Invalid API Key error

Issue: “Invalid API Key” or 401 error Solutions:
  • Verify your API key is correct (copy it again from Settings)
  • Make sure there are no extra spaces in the API key
  • Confirm the API key has the necessary permissions
  • Check that WALEAD_API_URL is set to https://app-api.walead.ai

​
Cannot find module error

Issue: “Cannot find module” or “ENOENT” errors Solutions:
  • Make sure you ran npm install in the walead-mcp folder
  • Verify the path in args points to the correct dist/index.js file
  • On Windows, use double backslashes: C:\\walead-mcp\\dist\\index.js

​
Connection errors

Issue: “Cannot resolve hostname” or “fetch failed” Solutions:
  • Verify WALEAD_API_URL is https://app-api.walead.ai (not https://api.walead.ai)
  • Check your internet connection
  • If using VPN/proxy, disable it temporarily
  • Check if your firewall is blocking Node.js

​
View Logs

To see detailed error logs: In Cursor:
  1. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
  2. Type: “Developer: Toggle Developer Tools”
  3. Go to the Console tab to see errors
In Claude Desktop:
  • Check the application logs in the developer console
Still having issues? Check the included GUIA_INSTALACION.md file in the MCP package for more detailed troubleshooting steps.