fupacat/eloqua-mcp-server

Oracle Eloqua MCP Server

A comprehensive Model Context Protocol (MCP) server for Oracle Eloqua Marketing Platform, providing AI applications with extensive access to Eloqua's marketing automation capabilities through 30+ tools covering the complete REST API.

🚀 Comprehensive API Coverage

This MCP server provides extensive coverage of Oracle Eloqua's REST API with 30+ tools organized into logical categories:

📊 Account Management

• list_accounts - List all accounts (companies) with search and pagination
• get_account - Get detailed account information
• create_account - Create new accounts with address and contact details

📈 Campaign Management

• list_campaigns - List all campaigns with pagination support
• get_campaign - Get detailed information about a specific campaign
• create_campaign - Create new campaigns with custom settings

👥 Contact Management

• search_contacts - Search contacts by email, name, or other criteria
• get_contact - Retrieve detailed contact information
• upsert_contact - Create new contacts or update existing ones with custom fields
• get_contact_activities - Get activity history for specific contacts
• list_contact_lists - List all contact lists
• get_contact_list - Get detailed contact list information
• list_contact_fields - List all available contact fields

📧 Email Management

• list_emails - List all email assets with search capabilities
• get_email - Get detailed email information and content
• create_email_deployment - Create and send email deployments to contacts or segments
• list_email_groups - List all email groups for subscription management

📝 Form Management

• list_forms - List all forms in your Eloqua instance
• get_form - Get detailed form information and structure
• get_form_submissions - Retrieve form submissions with pagination
• submit_form_data - Submit data to forms programmatically

🌐 Landing Page Management

• list_landing_pages - List all landing pages with search
• get_landing_page - Get detailed landing page information

🔄 Program Management

• list_programs - List all programs (advanced campaigns)
• get_program - Get detailed program information
• activate_program - Activate programs for execution
• deactivate_program - Deactivate running programs

🎪 Event Management

• list_events - List all event registrations
• get_event - Get detailed event information

🎯 Segment Management

• list_segments - List all contact segments

📊 Analytics & Reporting

• get_campaign_performance - Retrieve campaign performance metrics with date filtering
• get_contact_activities - Get detailed activity tracking for contacts

🔧 System Management

• get_current_user - Get information about the authenticated user

📦 Bulk Operations (Enterprise-Grade Data Management)

• create_contact_export - Create contact export definitions for bulk data extraction
• create_contact_import - Create contact import definitions for bulk data loading
• start_sync - Start import/export sync operations
• get_sync_status - Monitor sync operation progress and status

🏗 Architecture

This MCP server is built with:

• TypeScript for type safety and developer experience
• Zod for robust input validation and schema definition
• Model Context Protocol SDK for seamless AI integration
• Comprehensive error handling for production reliability
• Pagination support for handling large datasets efficiently
• Authentication management with Oracle Eloqua's Basic Auth

Prerequisites

• Node.js 18.0.0 or higher
• Oracle Eloqua account with API access
• Valid Eloqua credentials (company name, username, password)
• Proper Eloqua pod URL (e.g., secure.p02.eloqua.com for pod 02)

Installation

1. Clone or download this repository

2. Install dependencies:

   npm install
   

3. Copy the environment template:

   copy .env.example .env
   

4. Configure your Eloqua credentials in .env:

   ELOQUA_BASE_URL=https://secure.eloqua.com/API/REST/2.0
   ELOQUA_COMPANY=your-company-name
   ELOQUA_USERNAME=your-username
   ELOQUA_PASSWORD=your-password
   

Building

Build the TypeScript project:

npm run build

Running

Start the MCP server:

npm start

For development with automatic rebuilding:

npm run watch

Testing

Quick Validation (Recommended)

Run a fast connectivity and basic functionality check:

node quick-validation.mjs

Runtime: ~10-15 seconds

Comprehensive Smoke Test

Test all 30+ endpoints systematically:

node smoke-test.mjs

Runtime: ~2-3 minutes

Manual Testing with MCP Inspector

For detailed debugging and interactive testing:

# Terminal 1: Start the server
npm start

# Terminal 2: Start the inspector
npx @modelcontextprotocol/inspector build/index.js

Then open http://localhost:6274 in your browser.

See for comprehensive testing documentation.

Configuration

The server uses environment variables for Eloqua API authentication:

VS Code Integration

This project includes VS Code configuration for debugging MCP servers:

1. Open the project in VS Code
2. Use Ctrl+Shift+P and run "MCP: Add Server"
3. The server will be automatically detected via .vscode/mcp.json

Available Tasks

• Build MCP Server - Compile TypeScript (Ctrl+Shift+P → "Tasks: Run Task")
• Start MCP Server - Build and start the server
• Watch and Build - Continuous compilation during development

MCP Client Integration

To use this server with MCP clients like Claude Desktop, add it to your MCP configuration:

{
  "mcpServers": {
    "eloqua": {
      "command": "node",
      "args": ["path/to/eloqua-mcp-server/build/index.js"],
      "env": {
        "ELOQUA_COMPANY": "your-company",
        "ELOQUA_USERNAME": "your-username", 
        "ELOQUA_PASSWORD": "your-password"
      }
    }
  }
}

Security Considerations

• Never commit credentials - Always use environment variables
• Use application-specific passwords when available
• Implement IP restrictions in Eloqua if supported
• Monitor API usage to detect unusual activity
• Use HTTPS for all communications (handled by Eloqua API)

API Rate Limits

Oracle Eloqua enforces API rate limits. This server includes error handling for rate limit responses, but consider:

• Implementing exponential backoff for retries
• Caching frequently accessed data
• Batching operations when possible
• Monitoring your API usage in Eloqua

Error Handling

The server provides comprehensive error handling:

• Authentication errors - Invalid credentials or expired sessions
• API errors - Eloqua API-specific error responses
• Network errors - Connection timeouts and network issues
• Validation errors - Invalid input parameters

All errors are returned in a consistent format with descriptive messages.

📖 Usage Examples

Campaign Management

// List recent campaigns
await list_campaigns({ count: 10, page: 1 });

// Get campaign details
await get_campaign({ campaignId: "123" });

// Create a new campaign
await create_campaign({ 
  name: "Q1 Product Launch", 
  description: "Product launch campaign for Q1" 
});

Advanced Contact Operations

// Search for contacts by company
await search_contacts({ searchTerm: "Oracle", count: 25 });

// Get detailed contact information
await get_contact({ contactId: "456" });

// Create/update contact with custom fields
await upsert_contact({
  email: "john.doe@example.com",
  firstName: "John",
  lastName: "Doe",
  company: "Example Corp",
  customFields: {
    "C_Industry": "Technology",
    "C_CompanySize": "Enterprise"
  }
});

// Track contact activities
await get_contact_activities({ 
  contactId: "456", 
  activityType: "emailOpen" 
});

Bulk Data Operations

// Create contact export for data analysis
await create_contact_export({
  name: "Q1 Contact Export",
  fields: ["emailAddress", "firstName", "lastName", "company"],
  filter: "company='Oracle'"
});

// Set up contact import for bulk updates
await create_contact_import({
  name: "New Contacts Import",
  fields: ["emailAddress", "firstName", "lastName"],
  identifierFieldName: "emailAddress"
});

// Start sync operation
await start_sync({
  syncType: "export",
  definitionId: "789"
});

// Monitor sync progress
await get_sync_status({ syncId: "sync_123" });

Email Marketing Automation

// List all email assets
await list_emails({ count: 50 });

// Deploy email to segment
await create_email_deployment({
  emailId: "321",
  name: "Product Announcement Deploy",
  segmentId: "segment_456",
  sendAt: "2024-01-15T10:00:00Z"
});

// Deploy to specific contacts (max 100)
await create_email_deployment({
  emailId: "321",
  name: "VIP Customer Deploy",
  contactIds: ["contact_1", "contact_2", "contact_3"]
});

Program Workflow Management

// List automation programs
await list_programs({ search: "nurture" });

// Get program details
await get_program({ programId: "prog_123" });

// Activate program
await activate_program({ programId: "prog_123" });

// Deactivate when needed
await deactivate_program({ programId: "prog_123" });

Form and Landing Page Management

// List landing pages
await list_landing_pages({ search: "product" });

// Get form structure
await get_form({ formId: "form_123" });

// Submit form data programmatically
await submit_form_data({
  formId: "form_123",
  fieldValues: {
    "firstName": "Jane",
    "emailAddress": "jane@example.com",
    "company": "Tech Corp"
  },
  contactId: "contact_789"
});

Account and System Management

// List company accounts
await list_accounts({ search: "Oracle", count: 10 });

// Create new account
await create_account({
  name: "New Customer Corp",
  city: "San Francisco",
  country: "USA",
  businessPhone: "+1-555-0123"
});

// Get current user info
await get_current_user({});

Error Handling

All tools return consistent error responses:

{
  content: [
    {
      type: "text",
      text: "Error retrieving campaigns: Eloqua API error: 401 Unauthorized"
    }
  ]
}

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── types/            # TypeScript type definitions
└── utils/            # Utility functions

.vscode/
├── mcp.json          # MCP server configuration
└── tasks.json        # VS Code build tasks

.env.example          # Environment template
package.json          # Project dependencies
tsconfig.json         # TypeScript configuration

Adding New Tools

To add new Eloqua API tools:

1. Define the tool schema using Zod
2. Implement the API call using makeEloquaRequest()
3. Add error handling and response formatting
4. Register the tool with the MCP server

Example:

server.tool(
  "tool_name",
  "Tool description",
  {
    param: z.string().describe("Parameter description")
  },
  async ({ param }) => {
    try {
      const result = await makeEloquaRequest(`/api/endpoint/${param}`);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error: ${error.message}` }]
      };
    }
  }
);

Troubleshooting

Common Issues

"Cannot find module" errors

• Run npm install to install dependencies
• Ensure Node.js version is 18.0.0 or higher

Authentication failures

• Verify credentials in .env file
• Check that your Eloqua user has API access
• Ensure company name is correct (case-sensitive)

API timeout errors

• Check network connectivity
• Verify Eloqua service status
• Consider increasing timeout values

Permission errors

• Ensure your Eloqua user has appropriate permissions
• Check if specific APIs require admin access

Contributing

We welcome contributions! Please see our for details on:

• Development setup and workflow
• Code style and standards
• Testing requirements
• Submission guidelines

For quick reference:

1. Fork the repository
2. Create a feature branch
3. Make your changes and add tests
4. Run the full test suite: npm run test:full
5. Submit a pull request

📚 Documentation

• - Installation guide for developers and end users
• - Comprehensive testing documentation
• - Development and contribution guidelines
• - Version history and release notes
• - Latest test results and validation

📦 Distribution

For End Users

# Install from npm (when published)
npm install -g eloqua-mcp-server

# Quick setup test
eloqua-mcp-server --version

For Developers

# Clone and setup
git clone https://github.com/yourusername/eloqua-mcp-server.git
cd eloqua-mcp-server
npm install
npm run build
npm test

License

Apache License 2.0 - see file for details.

Support

For issues related to:

• This MCP server: Create an issue in this repository
• Oracle Eloqua API: Consult Eloqua documentation or support
• Model Context Protocol: Visit https://modelcontextprotocol.io

Resources

• Oracle Eloqua REST API Documentation
• Model Context Protocol Specification
• MCP TypeScript SDK
• VS Code MCP Integration