> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walead.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP (Cursor / Claude Desktop)
> Use the WaLead API as MCP tools inside Cursor, Claude Desktop, or any MCP client
## 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 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:
```bash theme={null}
cd /path/to/walead-mcp
npm install
```
### 3. Get Your API Key
1. Go to [app.walead.ai](https://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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
| Tool | Description |
| ------------------------------------------ | ------------------------------------------------------------- |
| `walead_list_campaigns` | List campaigns (optional: status, search) |
| `walead_get_campaign` | Get one campaign by ID |
| `walead_create_campaign` | Create campaign (name) |
| `walead_add_leads` | Add leads to a campaign (leads or linkedinUrls) |
| `walead_list_conversations` | List unibox conversations |
| `walead_get_conversation` | Get one conversation with messages |
| `walead_send_message` | Send message in a conversation |
| `walead_mark_conversation_read` | Mark conversation as read |
| `walead_create_embed_link_account_session` | Create 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.