Cordial MCP Standalone Extension

A standalone TypeScript MCP extension for the Cordial marketing platform, designed to work with Claude Desktop and as an npm package.

Features

All tools from the main MCP server:

• get_account_info - Retrieve comprehensive account configuration
• get_customer_info - Get customer details by email
• get_batch_emails_by_created_date - Fetch emails by creation date
• get_batch_emails_by_send_date - Fetch emails by send date
• get_email_template - Get specific email template
• get_audience_count_by_criteria - Calculate audience size by criteria
• get_audience_count_by_id - Get audience count by ID

Quick Start with npx

Run directly without installation:

# Set your API credentials
export API_KEY="your-cordial-api-key"
export API_URL="https://api.use1.cordial.io"  # Optional, defaults to this URL

# Run with npx
npx cordialMCP

Or inline:

API_KEY="your-key" npx cordialMCP

Installation Options

Option 1: Run with npx (Recommended for Users)

No installation needed:

API_KEY="your-key" npx cordialMCP

Option 2: Global Installation

Install once, run anywhere:

npm install -g cordialmcp
cordialMCP

Option 3: Claude Desktop Extension

For Claude Desktop integration:

1. Install Dependencies

   cd standalone
   npm install

2. Build the Extension

   npm run build

3. Pack the Extension

   npm run pack

   This creates a cordial-mcp.mcpb file.

4. Install in Claude Desktop Drag and drop the .mcpb file into Claude Desktop, or double-click to install.

5. Configure Claude Desktop will prompt you for:

   • API URL: Your Cordial API URL (default: https://api.cordial.com)
   • API Key: Your Cordial API key (stored securely in OS keychain)

Authentication

The extension uses the same authentication pattern as the main server (cordial_auth.py):

• The API key is used directly as a Bearer token
• Token serves as both authentication credential and client identifier
• Credentials are stored securely in the OS keychain

Development

Watch Mode

For development with auto-rebuild:

npm run dev

Project Structure

standalone/
├── manifest.json          # Extension metadata and user config
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── cordial-client.ts # Cordial API client with auth
└── server/               # Compiled JavaScript output

Configuration

The extension reads configuration from environment variables automatically provided by Claude Desktop:

• API_URL - Cordial API base URL
• API_KEY - Cordial API authentication key

These map to the user_config section in manifest.json.