Loops.so MCP Server

A Model Context Protocol (MCP) server for integrating with the Loops.so email platform API. This server provides tools for managing contacts, sending events, and handling transactional emails through Claude Desktop and other MCP-compatible clients.

Features

The server implements the following Loops.so API endpoints as MCP tools:

• Contact Management

  • create_contact - Add new contacts to your audience
  • update_contact - Update existing contact information
  • find_contact - Search for contacts by email or user ID
  • delete_contact - Remove contacts from your audience

• Email Operations

  • send_event - Trigger automated emails in loops
  • send_transactional_email - Send immediate transactional emails

• Data Retrieval

  • get_mailing_lists - List all your mailing lists
  • get_custom_fields - Get all custom contact properties

Installation

Option 1: Install from npm (Recommended)

npm install -g loops-mcp-server

Option 2: Install from Source

# Clone or download the repository
git clone <repository-url>
cd loops-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Setup Instructions

1. Get Your Loops API Key

1. Log in to your Loops.so account
2. Navigate to Settings → API
3. Copy your API key

2. Configure Your MCP Client

Choose your editor/platform and follow the configuration steps below.

Option A: Using npx (Recommended)

This automatically downloads and runs the latest version:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

Option B: Global Installation

If you prefer to install globally first:

npm install -g loops-mcp-server

Then use in config:

{
  "mcpServers": {
    "loops": {
      "command": "loops-mcp-server",
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

Editor-Specific Configuration

Claude Desktop

Config File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

After configuration: Completely quit and restart Claude Desktop.

Cursor IDE

Config File Location:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

Alternative: Cursor may also support MCP configuration through:

• Settings UI: Cmd/Ctrl + , → Search for "MCP"
• Workspace settings: .cursor/mcp.json

After configuration: Restart Cursor IDE.

Windsurf / Codeium

Config File Location:

• macOS: ~/.codeium/windsurf/mcp_config.json
• Windows: %APPDATA%/.codeium/windsurf/mcp_config.json
• Linux: ~/.config/.codeium/windsurf/mcp_config.json

Configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "disabled": false,
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

After configuration: Use the refresh button in Windsurf's MCP settings UI or restart Windsurf.

VS Code (with MCP Extension)

Prerequisites:

• Install the MCP extension for VS Code (e.g., modelcontextprotocol.vscode-mcp)

Config File Location:

• Workspace: .vscode/mcp.json
• User: VS Code Settings → MCP Configuration

Configuration (.vscode/mcp.json):

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

Alternative (Settings UI):

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "MCP"
3. Edit MCP Server Configuration
4. Add the loops server configuration

After configuration: Reload VS Code window or restart VS Code.

Continue.dev

Config File Location:

• ~/.continue/config.json (or workspace .continue/config.json)

Configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

After configuration: Restart Continue.dev.

Aider

Configuration: Add to your aider config file (usually ~/.aider.conf or aider.conf):

mcp:
  servers:
    loops:
      command: npx
      args: ["-y", "loops-mcp-server"]
      env:
        LOOPS_API_KEY: "your-loops-api-key-here"

After configuration: Restart aider.

Cline (VS Code Extension)

Config File Location:

• VS Code Settings or workspace .cline/mcp.json

Configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

General MCP Client Configuration

If you're using a different MCP-compatible client, use this standard configuration:

{
  "mcpServers": {
    "loops": {
      "command": "npx",
      "args": ["-y", "loops-mcp-server"],
      "env": {
        "LOOPS_API_KEY": "your-loops-api-key-here"
      }
    }
  }
}

Key Points:

• Replace your-loops-api-key-here with your actual Loops API key
• The -y flag in npx auto-confirms package installation
• Ensure Node.js 18+ is installed and in your PATH
• Restart your editor/client after configuration changes

Development

Run in Development Mode

For development with auto-reload, use:

npm run dev

Build for Production

npm run build

Run Built Server

npm start

Usage Examples

Once configured, you can interact with the Loops API through Claude Desktop:

• "Create a contact with email [email protected]"
• "Find the contact with email [email protected]"
• "Send an event called 'welcome' to [email protected]"
• "Show me all my mailing lists"
• "Update the contact [email protected] to be unsubscribed"
• "Delete the contact with email [email protected]"

API Rate Limits

Loops.so has a baseline rate limit of 10 requests per second per team. The server includes proper error handling for rate limit responses (429).

Error Handling

The server includes comprehensive error handling and will return meaningful error messages if API calls fail. All errors are properly formatted and returned to the MCP client.

Security

• Never commit your LOOPS_API_KEY to version control
• The API key is only read from environment variables
• The server uses Bearer token authentication as required by Loops.so

Troubleshooting

Common Issues

"Command not found" or "executable file not found in $PATH"

• Ensure Node.js 18+ is installed: node --version
• If using npx, ensure npm is in your PATH
• Try using the full path: "command": "node", "args": ["-m", "loops-mcp-server"]

"LOOPS_API_KEY environment variable is required"

• Verify the API key is set correctly in your config file
• Check for typos in the environment variable name (must be LOOPS_API_KEY)
• Ensure the config file JSON is valid

Server not connecting

• Restart your editor/client completely
• Check editor logs for error messages
• Verify your API key at https://app.loops.so → Settings → API
• Test the server manually: LOOPS_API_KEY=test npx -y loops-mcp-server (will error, but confirms it runs)

Connection timeout

• Check your internet connection (npx downloads the package)
• Try installing globally first: npm install -g loops-mcp-server
• Check firewall/proxy settings

Getting Help

• Documentation: GitHub Repository
• Issues: Report a Bug
• Loops.so API Docs: API Reference

Testing

For comprehensive testing instructions, see TESTING_GUIDE.md.

Quick test:

export LOOPS_API_KEY="your-api-key"
node test-mcp-client.js

License

ISC