@kelpi/mcp

MCP (Model Context Protocol) server for Kelpi customer engagement automation. This package enables AI assistants like Claude to interact with the Kelpi API for managing email templates, automation flows, contacts, and events.

What is Kelpi MCP Server?

The Kelpi MCP Server provides a standardized interface for AI assistants to:

• Authenticate with your Kelpi workspace
• Create and manage email templates
• Build and activate automation flows
• Create contacts and track events
• Generate SDK integration snippets

Installation

Using npx (Recommended)

No installation required. Configure Claude Desktop to use npx:

{
  "mcpServers": {
    "kelpi": {
      "command": "npx",
      "args": ["@kelpi/mcp"]
    }
  }
}

Global Installation

npm install -g @kelpi/mcp

Then configure Claude Desktop:

{
  "mcpServers": {
    "kelpi": {
      "command": "kelpi-mcp"
    }
  }
}

Claude Desktop Configuration

1. Open Claude Desktop settings
2. Navigate to the MCP Servers section
3. Add the following configuration to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kelpi": {
      "command": "npx",
      "args": ["@kelpi/mcp"]
    }
  }
}

4. Restart Claude Desktop
5. The Kelpi tools will now be available in your conversations

Available Tools

Authentication

kelpi_login

Authenticate with your Kelpi workspace using device code flow.

Usage: Just ask Claude to "log in to Kelpi" or "authenticate with Kelpi"

kelpi_status

Check current authentication status and workspace information.

Returns:

• authenticated: Whether you're logged in
• workspace_id: Your workspace ID
• workspace_name: Your workspace name
• key_type: API key type (public/secret)

Templates

kelpi_create_template

Create a new email template.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | slug | string | Yes | URL-friendly identifier (lowercase, hyphens) | | name | string | Yes | Display name for the template | | subject | string | Yes | Email subject line | | body_html | string | Yes | HTML content of the email | | variables | array | No | Template variables with defaults |

Example:

Create an email template called "welcome-email" with subject "Welcome to Our Service!" and body with a greeting for {{name}}

kelpi_list_templates

List all templates in your workspace.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | limit | number | No | Maximum templates to return (1-100) | | offset | number | No | Number of templates to skip |

Flows

kelpi_create_flow

Create a new automation flow.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | definition | object | Yes | Flow definition object | | definition.name | string | Yes | Flow name | | definition.trigger_type | string | Yes | "event", "segment", or "manual" | | definition.trigger_event | string | Conditional | Required if trigger_type is "event" | | definition.steps | array | No | Flow steps (delays, emails, conditions) |

Example:

Create a welcome flow that triggers on user.signup event and sends a welcome email after 1 hour

kelpi_list_flows

List all flows in your workspace.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | status | string | No | Filter by status: "draft", "active", "archived" | | limit | number | No | Maximum flows to return (1-100) | | offset | number | No | Number of flows to skip |

kelpi_activate_flow

Activate an inactive flow.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | flow_id | string | Yes | UUID of the flow to activate |

Contacts

kelpi_create_contact

Create a new contact.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | Contact's email address | | name | string | No | Contact's name | | properties | object | No | Custom properties |

Events

kelpi_track_event

Track a custom event for a contact.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | email | string | Yes | Contact's email address | | event_name | string | Yes | Name of the event | | properties | object | No | Event properties |

Example:

Track a "purchase_completed" event for [email protected] with product_id "prod_123"

SDK Integration

kelpi_get_public_key

Get or create a public API key for client-side SDK usage.

Returns: API key object with the public key for SDK initialization

kelpi_get_sdk_snippet

Generate SDK integration code for your application.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | framework | string | Yes | "react", "nextjs", "vanilla", "node", or "express" |

Example:

Generate a React SDK snippet for Kelpi integration

Example Workflows

Onboarding Flow Setup

1. "Log in to Kelpi"
2. "Create a welcome email template with subject 'Welcome!' and personalized greeting"
3. "Create a flow that triggers on user.signup and sends the welcome email after 30 minutes"
4. "Activate the welcome flow"

SDK Integration

1. "Get my Kelpi public key"
2. "Generate a React SDK snippet"
3. "Create a test contact with email [email protected]"
4. "Track a signup event for [email protected]"

Error Handling

The Kelpi MCP Server provides user-friendly error messages with actionable hints:

| Error | Hint | |-------|------| | "Authentication required" | Run kelpi_login first to authenticate | | "API key is invalid or expired" | Run kelpi_login to get a new API key | | "Resource not found" | Check that the ID is correct | | "Resource already exists" | Use a different identifier or update the existing resource | | "Validation error" | Fix the validation errors and try again |

Development

Setup

# Clone the repository
git clone https://github.com/kelpi-ai/kelpi.git
cd kelpi/packages/mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Project Structure

packages/mcp/
  src/
    lib/
      api-client.ts      # HTTP client with retry logic
      config.ts          # Configuration management
      errors.ts          # Custom error classes
      error-formatter.ts # User-friendly error formatting
      tool-registry.ts   # MCP tool registration
    tools/
      auth/              # Login and status tools
      flows/             # Flow management tools
      templates/         # Template management tools
      contacts/          # Contact management tools
      events/            # Event tracking tools
      sdk/               # SDK integration tools
    server.ts            # MCP server implementation
    index.ts             # Package entry point
  __tests__/
    unit/                # Unit tests
    integration/         # Integration tests

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests first (TDD)
4. Implement your feature
5. Ensure all tests pass
6. Submit a pull request

License

MIT

Support

• Documentation
• GitHub Issues
• Discord Community