LeadSync for Claude and other AI assistants
An MCP server and a set of skills that let Claude (and Cursor, Codex or any MCP client) set up and troubleshoot your LeadSync account: connect Meta lead forms to Google Sheets, CRMs and email, map the fields, add autoresponders, send test leads and find out what happened to a lead. More at leadsync.me/mcp.
Install
You need Node.js 20 or later and a LeadSync account (a free trial works).
Claude Code (the server plus the skills):
npx @leadsync/skills --claude
npx @leadsync/skills login
Cursor: npx @leadsync/skills --cursor, then npx @leadsync/skills login.
Codex: npx @leadsync/skills --codex, then npx @leadsync/skills login.
--all installs into every one of these that is set up on your computer. --project-dir <dir> puts Cursor's mcp.json and the skills in a project folder instead of your home folder (Claude Code and Codex still register the server for your user). --uninstall removes the server and the skills again.
Claude Code plugin (an alternative to --claude; use one or the other, not both):
claude plugin marketplace add lmoulton/leadsync-skills
claude plugin install leadsync@leadsync-skills
npx @leadsync/skills login
Claude Desktop, Cursor or any MCP client: add this to the client's MCP config:
{
"mcpServers": {
"leadsync": {
"command": "npx",
"args": ["-y", "@leadsync/mcp"],
"env": { "LEADSYNC_API_KEY": "ls_live_your_key_here" }
}
}
}
Claude Desktop: Settings, Developer, Edit Config. Cursor: ~/.cursor/mcp.json. Either put your key in the env line or run npx @leadsync/skills login and delete the env line: a key in env always wins over the one login saves, including the placeholder.
Restart the assistant after installing or signing in, then try: "Show me every page and form in my LeadSync account and where their leads go."
Getting a key
Either:
- run
npx @leadsync/skills login: it opens LeadSync in your browser, you approve the device, and the key is saved for you; or - create a key in LeadSync under Account, Settings, API keys (https://leadsync.me/account/settings#api-keys) and paste it into
~/.leadsync/.envas one line:LEADSYNC_API_KEY=ls_live_....
The key file is ~/.leadsync/.env (folder mode 700, file mode 600). The server reads each setting from its environment first, then from that file, so no assistant config needs to hold the key. One key covers every page and client in that LeadSync account; an account can have up to 10 active keys. Revoke a key under Account, Settings, API keys.
Keep the key private, like a password. The server never prints it, and the skills tell Claude never to ask for it in chat.
What Claude can do
| Tool | What it does |
|---|---|
get_me |
Shows who the key belongs to and its scopes. |
find_accounts |
Finds accounts by email, username or page name (LeadSync staff keys only). |
get_connections |
Shows the sources (pages) to lists graph (each list with active, mapping_set and destinations) plus the account's connections with their autoresponders. |
refresh_forms |
Re-reads a page's lead forms from Meta, with each form's question keys (forms[].questions[].key) to use when mapping. |
attach_form |
Connects a form to a destination by creating a list. Send mapping and settings in the same call: a new list replays up to 7 days of leads immediately. |
set_list_active |
Pauses or resumes delivery for a list. |
set_mapping |
For an existing list: replaces the whole mapping with what you send; settings keys are merged. Send settings alone to leave the mapping untouched. |
get_destination_fields |
Shows the fields a destination connection accepts. |
list_autoresponders |
Lists the account's autoresponders and the connection each is attached to (no filter; autoresponders are never per list). |
create_autoresponder |
Adds an autoresponder to a connection. |
list_leads |
Lists recent leads and their delivery status. Defaults to the last 7 days and 50 rows; absence is proof only if the window covered the lead's time. |
resend_lead |
Requeues a lead's failed or held deliveries. |
send_test_lead |
Asks Meta to create a test lead for a list. |
list_email_log |
Lists emails sent for a list (notifications and autoresponders). |
One prompt, connect_form_to_destination, walks the assistant through attaching a form, mapping fields, adding an autoresponder, sending a test lead and checking it arrived.
The skills (Claude Code and Codex):
leadsync-setup: checks the key withget_me, explains scopes, and where keys come from.connecting-lead-forms: maps fields, attaches a form to a destination with the mapping in the same call, adds an autoresponder, tests and verifies.troubleshooting-lead-delivery: classifies a missing lead, then decides whether to resend or escalate.
The API itself is documented at leadsync.me/developers; docs/openapi.yaml here is a copy.
Safety rules
- On a customer account, state what you will do and wait for the human's yes before any write (attach, mapping, pause or resume, autoresponder, test lead, resend). Reads need no yes. The flags
acknowledge_customer_impact,acknowledge_shared_connectionandoverride_limitsare never sent without the human's yes. - Test leads go to the list's real destinations, and on a customer account they can email the customer. Ask before sending one.
- Creating an autoresponder on a customer account starts emailing that customer's prospects, so it is gated like any other write.
- Map before you attach: attaching a form to a new list replays up to 7 days of that form's leads to the destination.
set_mappingreplaces the whole mapping and no tool can read the current one, so never send a partial mapping to a list that already has one.- Autoresponders belong to a connection: every lead through that connection gets every autoresponder on it.
- Resending a lead can create duplicates in the destination, and that cannot be undone.
Settings
| Variable | What it does |
|---|---|
LEADSYNC_API_KEY |
Required. Your API key. Never written to logs or output. |
LEADSYNC_API_BASE |
Optional. Defaults to https://leadsync.me. |
LEADSYNC_ACCOUNT |
Optional. LeadSync staff only. |
Each is read from the environment first, then from ~/.leadsync/.env.
Development
npm test # the installer (node --test)
cd packages/mcp
npm ci
npm test # the server (vitest)
npm run build
The installer (installer/, published as @leadsync/skills) has no dependencies and no build step. The server (packages/mcp, published as @leadsync/mcp) is TypeScript. Release steps are in RELEASING.md; security reports go to the address in SECURITY.md.
Licence
MIT. See LICENSE.