MCP Integration

Model Context Protocol for AI Assistants

Model Context Protocol (MCP) is an open standard introduced by Anthropic that allows AI assistants (like Claude, Cursor, VS Code Copilot) to integrate with external tools and data sources.

Ask questions: 'How many subscribers do I have?'

Manage subscribers using natural language

Send messages: 'Send an email to jan@example.com'

Get statistics: 'Analyze my list quality'

How It Works

The AI assistant communicates with the MCP server via the STDIO protocol, and the MCP server performs operations on NetSendo using the REST API v1.

┌─────────────────┐     STDIO      ┌─────────────────┐     HTTP/S     ┌─────────────────┐
│  Claude/Cursor  │ ◄──────────► │   MCP Server    │ ◄───────────► │    NetSendo     │
│   (AI Client)   │               │   (Docker/npx)  │               │  (Your inst.)   │
└─────────────────┘               └─────────────────┘               └─────────────────┘

Installation

Remote Installation (npx)

Recommended

Best for NetSendo hosted on a server (e.g. https://app.mycompany.com)

Requirements

Node.js 18+
API Key from NetSendo

Steps

Generate API Key: Settings → API Keys
Install Node.js from nodejs.org
Configure your AI tool using the configuration below

Claude Desktop and Cursor

{
  "mcpServers": {
    "netsendo": {
      "command": "npx",
      "args": [
        "-y",
        "@netsendo/mcp-client",
        "--url",
        "https://your-domain.com",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

VS Code `.vscode/mcp.json`

VS Code reads MCP servers from .vscode/mcp.json in your workspace (or from your user profile via the "MCP: Open User Configuration" command). This file uses a top-level "servers" key instead of "mcpServers".

{
  "servers": {
    "netsendo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@netsendo/mcp-client",
        "--url",
        "https://your-domain.com",
        "--api-key",
        "YOUR_API_KEY"
      ]
    }
  }
}

Replace https://your-domain.com with your NetSendo instance URL and YOUR_API_KEY with your generated API key.

Local Installation (Docker)

Best for NetSendo running locally on your computer in Docker

Requirements

Docker installed and running
Access to the NetSendo docker-compose.yml file

Steps

Generate API Key: Settings → API Keys
Mark the API key for MCP in settings
Add the key to .env file: MCP_API_KEY=your-api-key
Build the MCP container: docker compose build mcp
Configure your AI tool using the configuration below

Claude Desktop and Cursor

{
  "mcpServers": {
    "netsendo": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/path/to/NetSendo/docker-compose.yml",
        "run",
        "--rm",
        "-i",
        "mcp"
      ]
    }
  }
}

Replace /path/to/NetSendo with the full path to your NetSendo installation directory.

In VS Code, put the same "netsendo" entry under a top-level "servers" key in .vscode/mcp.json, and add "type": "stdio".

Configuration File Locations

Client	File Location
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor IDE	Settings → MCP → Add Server
VS Code	.vscode/mcp.json

Supported AI Clients

🤖

Claude Desktop

Official Claude desktop app from Anthropic

💻

Cursor IDE

IDE with built-in AI for developers

📝

VS Code

Visual Studio Code with GitHub Copilot (agent mode)

Available Features

Subscribers

Manage contacts – add, edit, delete

Contact Lists

Browse and organize mailing lists

Email Messages

Send personalized email messages

SMS Messages

Send SMS messages to contacts

Statistics

Check account and deliverability statistics

Available Tools

Version 1.5.1 of @netsendo/mcp-client provides 77 tools in 15 groups.

Subscribers (6)

Tool	Description
list_subscribers	List subscribers with filtering and pagination
get_subscriber	Get a subscriber by ID or email address
create_subscriber	Create a subscriber with optional list and tag assignments
update_subscriber	Update a subscriber's data
delete_subscriber	Permanently delete a subscriber
sync_subscriber_tags	Replace all tags assigned to a subscriber

Contact lists, tags and custom fields (9)

Tool	Description
list_contact_lists	Get all contact lists with subscriber counts and default mailbox
get_contact_list	Get the details of a contact list, including its default mailbox
get_list_subscribers	Get the subscribers of a contact list
get_list_stats	List snapshot: members by status, engagement, 30-day growth and sending settings
create_contact_list	Create an email or SMS contact list
update_contact_list	Update a list's settings (only the fields you pass change)
delete_contact_list	Delete a contact list; the contacts stay in the account
list_tags	Get all available tags
list_custom_fields	Get all custom field definitions

List members (6)

Tool	Description
add_list_members	Attach existing contacts to a list
remove_list_members	Detach contacts from a list and cancel their queued messages
set_member_status	Change membership status: active, inactive, unsubscribed or bounced
copy_list_members	Copy contacts to another list of the same channel
move_list_members	Move contacts to another list of the same channel
tag_list_members	Add or remove tags across a segment of a list

Import (2)

Tool	Description
preview_list_import	Dry-run an import: column mapping, invalid addresses and duplicates, nothing is written
import_subscribers	Import contacts onto a list from CSV, TSV, JSON or plain addresses

Export (3)

Tool	Description
export_list	Export list members inline as JSON, CSV or NDJSON, with filters
get_export_fields	List the columns available for export, including custom fields
queue_list_export	Queue a full CSV export; the account owner gets a download link

List hygiene (5)

Tool	Description
analyze_list_health	Read-only hygiene report with a 0–100 health score and recommendations
clean_list	Apply an action to members in selected problem categories (dry run by default)
dedupe_list	Merge duplicate addresses, including Gmail dot and +tag aliases
verify_list_emails	Check deliverability: syntax, disposable and role addresses, typo domains, MX records
get_hygiene_options	Return the categories and actions accepted by clean_list

Suppression list (3)

Tool	Description
list_suppressions	Show the account-wide do-not-mail list with reasons and dates
suppress_emails	Add addresses to the do-not-mail list and unsubscribe them from every list
unsuppress_emails	Lift suppression for addresses (does not resubscribe anyone)

Activity and engagement (3)

Tool	Description
get_list_activity	Event feed for a list: signups, unsubscribes, bounces, sends, opens and clicks
get_list_engagement	List performance: growth, churn, open and click rates, top messages and links
get_subscriber_activity	Full history of one contact: lists, tags, queued messages and timeline

Email and SMS messages (6)

Tool	Description
list_mailboxes	Get available sending mailboxes
send_email	Send a single email to a subscriber
get_email_status	Check email delivery status
list_sms_providers	Get available SMS providers
send_sms	Send a single SMS to a subscriber or phone number
get_sms_status	Check SMS delivery status

Campaigns (10)

Tool	Description
list_campaigns	List email and SMS campaigns with filtering
get_campaign	Get campaign details, including lists and exclusions
create_campaign	Create an email or SMS campaign (saved as a draft)
update_campaign	Update a draft or scheduled campaign
set_campaign_lists	Set the recipient lists of a campaign
set_campaign_exclusions	Set exclusion lists whose subscribers will not receive the campaign
schedule_campaign	Schedule a campaign for later, with time zone support
send_campaign	Send a campaign now or activate an autoresponder
get_campaign_stats	Get sending statistics for a campaign
delete_campaign	Delete a draft or scheduled campaign

A/B tests (7)

Tool	Description
list_ab_tests	List A/B tests, filtered by status or campaign
create_ab_test	Create an A/B test for a campaign
add_ab_variant	Add a variant to an A/B test
start_ab_test	Start an A/B test (requires at least 2 variants)
end_ab_test	End a running test and optionally pick the winner
get_ab_test_results	Get detailed results and statistics of a test
delete_ab_test	Delete an A/B test that is not running

Funnels (automation) (12)

Tool	Description
list_funnels	List automation funnels
get_funnel	Get a funnel with all its steps and statistics
create_funnel	Create an automation funnel
update_funnel	Rename a funnel or change its trigger
add_funnel_step	Add a step to a funnel and connect it
update_funnel_step	Change a step's settings and connections
delete_funnel_step	Delete a step and reconnect the funnel around it
enroll_subscriber_in_funnel	Put a subscriber into an active funnel right away
activate_funnel	Activate a funnel for new subscribers
pause_funnel	Pause a funnel
get_funnel_stats	Get funnel statistics: subscriber counts and completion rates
delete_funnel	Delete a funnel (pause it first)

Notifications (2)

Tool	Description
send_notification	Post a notification to the account owner's notification centre
list_notifications	Read the owner's recent notifications and unread count

Personalization (1)

Tool	Description
list_placeholders	Get the placeholders for personalizing email and SMS content

Account (2)

Tool	Description
test_connection	Test the API connection and credentials
get_account_info	Get information about the connected account

More tool groups (automations, forms, templates, webhooks…) are coming in the next release of the MCP client.

Example Queries

"Show my mailing lists"

"How many subscribers do I have?"

"Add subscriber jan@example.com to Newsletter list"

"Send a welcome message to anna@example.com"

"Analyze the quality of my mailing list"

Security

🔐 API keys are never logged or exposed

🔒 All API calls respect NetSendo permissions

⚡ Rate limiting: 60 requests/minute

🚫 Sensitive data (passwords, payments) is never returned

📝 All operations are logged in the activity log

Troubleshooting

Connection Failed

Make sure NetSendo is running and accessible
Check if the API key is valid
Verify the URL is correct (include https://)

Tools Not Appearing

Restart your AI tool after configuration changes.

npx Command Not Found

Install Node.js from nodejs.org (includes npm/npx).

Multiple NetSendo Instances

You can connect to multiple NetSendo instances using different server names:

{
  "mcpServers": {
    "netsendo-production": {
      "command": "npx",
      "args": ["-y", "@netsendo/mcp-client", "--url", "https://app.company.com", "--api-key", "prod-key"]
    },
    "netsendo-staging": {
      "command": "npx",
      "args": ["-y", "@netsendo/mcp-client", "--url", "https://staging.company.com", "--api-key", "staging-key"]
    }
  }
}

Documentation Links

Full NetSendo MCP Documentation Model Context Protocol npm package @netsendo/mcp-client

MCP Integration

How It Works

Installation

Requirements

Steps

Claude Desktop and Cursor

VS Code .vscode/mcp.json

Requirements

Steps

Claude Desktop and Cursor

Configuration File Locations

Supported AI Clients

Available Features

Subscribers

Contact Lists

Email Messages

SMS Messages

Tags

Statistics

Available Tools

Subscribers (6)

Contact lists, tags and custom fields (9)

List members (6)

Import (2)

Export (3)

List hygiene (5)

Suppression list (3)

Activity and engagement (3)

Email and SMS messages (6)

Campaigns (10)

A/B tests (7)

Funnels (automation) (12)

Notifications (2)

Personalization (1)

Account (2)

Example Queries

Security

Troubleshooting

Multiple NetSendo Instances

Documentation Links

VS Code `.vscode/mcp.json`