IRISeller MCP Server

A Model Context Protocol (MCP) server that provides access to the IRISeller AI Agent Ecosystem, enabling external systems to leverage advanced sales AI capabilities.

Overview

The IRISeller MCP Server exposes 26 powerful tools that give external systems access to:

• 7 AI Agents: Lead qualification, prospecting, personalization, sequencing, social selling, nurturing, and objection handling
• Multi-CRM Data: Real-time access to Salesforce, Dynamics, and Oracle CRM data
• 6 Workflows: Complete multi-agent sales processes
• Sales Intelligence: Company research, forecasting, and analytics
• Email Automation: Email detection, sending, campaigns, templates, and status monitoring
• Web Search: Real-time web search capabilities using Claude's native web search tool

Features

🤖 AI Agent Tools

• Lead Qualification: BANT analysis with AI-powered insights
• Company Research: Multi-source intelligence gathering
• Personalization: AI-generated personalized outreach
• Workflow Execution: Complete multi-agent sales processes
• Asynchronous Execution: Robust handling of long-running agent tasks with completion polling and result retrieval

📊 CRM Integration

• Multi-CRM Support: Salesforce, Microsoft Dynamics, Oracle CX
• Real-time Data: Live lead, opportunity, contact, and account data
• Advanced Querying: Filtering, sorting, and pagination

📈 Sales Intelligence

• Forecasting: AI-powered sales predictions
• Analytics: Performance metrics and insights
• Health Monitoring: Service status and agent availability

📧 Email Automation

• Email Detection: Monitor incoming emails with advanced filtering
• Email Sending: Send personalized emails with template support
• Campaign Management: Automated email sequences and tracking
• Template Management: Create and manage email templates
• Status Monitoring: Real-time email system health and statistics

Quick Start

Option 1: NPX (Recommended)

Run directly with npx - no installation required:

npx @iriseller/mcp-server@latest --email your-email@example.com --password your-password --api-url https://beta.iriseller.com

Option 2: Global Installation

# Install globally
npm install -g @iriseller/mcp-server

# Run with credentials
iriseller-mcp-server --email your-email@example.com --password your-password

Option 3: Local Development

cd packages/mcp-server
npm install
npm run build
npm start

CLI Options

iriseller-mcp-server --help

Options:
  --email <email>           IRISeller account email
  --password <password>     IRISeller account password  
  --api-url <url>          IRISeller API URL (default: "https://beta.iriseller.com")
  --crewai-url <url>       CrewAI API URL
  --debug                  Enable debug mode
  --jwt-secret <secret>    JWT secret for token generation
  -h, --help               display help for command

Environment Variables

You can also use environment variables instead of CLI options:

# IRISeller Backend API Configuration
IRISELLER_API_URL=https://beta.iriseller.com
CREWAI_API_URL=http://localhost:8001
CRM_CONNECT_API_URL=https://beta.iriseller.com/api/crm-connect

# Authentication
IRISELLER_EMAIL=your-email@example.com
IRISELLER_PASSWORD=your-password
JWT_SECRET=your_jwt_secret_here

# Optional: Debug mode
DEBUG=true

Available Tools

Core CRM Tools

qualify_lead

Analyze and qualify leads using IRISeller's BANT framework with AI-powered insights.

{
  "name": "qualify_lead",
  "arguments": {
    "contact_name": "John Smith",
    "company_name": "TechCorp Inc",
    "title": "VP of Sales",
    "industry": "Technology",
    "email": "john@techcorp.com"
  }
}

query_crm

Search and retrieve data from multiple CRM systems.

{
  "name": "query_crm",
  "arguments": {
    "entity_type": "leads",
    "filters": {
      "status": "Open",
      "industry": "Technology"
    },
    "limit": 10
  }
}

research_company

Perform comprehensive company research using AI agents.

{
  "name": "research_company",
  "arguments": {
    "company_name": "TechCorp Inc",
    "research_depth": "comprehensive",
    "include_competitors": true
  }
}

AI Agent Tools

execute_agent

Execute individual AI agents for specific sales tasks.

{
  "name": "execute_agent",
  "arguments": {
    "agent_name": "personalization",
    "input_data": {
      "prospect_data": {
        "name": "John Smith",
        "company": "TechCorp Inc"
      },
      "message_type": "email"
    }
  }
}

get_agent_results

Retrieve results from a completed or running agent execution.

{
  "name": "get_agent_results",
  "arguments": {
    "execution_id": "abc123-def456-ghi789",
    "wait_for_completion": true,
    "timeout_seconds": 30
  }
}

wait_for_agent_completion

Wait for an agent execution to complete and return final results.

{
  "name": "wait_for_agent_completion",
  "arguments": {
    "execution_id": "abc123-def456-ghi789",
    "timeout_seconds": 120,
    "check_interval_seconds": 5
  }
}

execute_workflow

Execute multi-agent workflows for complete sales processes.

{
  "name": "execute_workflow",
  "arguments": {
    "workflow_type": "full_sdr_workflow",
    "input_data": {
      "company_name": "TechCorp Inc",
      "contact_name": "John Smith"
    }
  }
}

personalize_outreach

Generate personalized outreach messages using AI.

{
  "name": "personalize_outreach",
  "arguments": {
    "prospect_data": {
      "name": "John Smith",
      "company": "TechCorp Inc",
      "title": "VP of Sales"
    },
    "message_type": "email",
    "tone": "professional"
  }
}

Analytics Tools

forecast_sales

Generate sales forecasts and pipeline analysis.

{
  "name": "forecast_sales",
  "arguments": {
    "time_period": "90d",
    "include_scenarios": true
  }
}

Web Search Tools

web_search

Search the web for real-time information using Claude's native web search capability.

{
  "name": "web_search",
  "arguments": {
    "query": "latest AI trends 2024",
    "max_uses": 3,
    "allowed_domains": ["nature.com", "arxiv.org", "techcrunch.com"],
    "user_location": {
      "type": "approximate",
      "city": "San Francisco",
      "region": "California", 
      "country": "US",
      "timezone": "America/Los_Angeles"
    }
  }
}

Parameters:

• query (required): The search query to execute
• max_uses (optional): Maximum number of search operations (1-5, default: 3)
• allowed_domains (optional): Array of domains to restrict search to
• blocked_domains (optional): Array of domains to exclude from search
• user_location (optional): Location context for localized results
  • type: Must be "approximate"
  • city: City name
  • region: State or region name
  • country: Country code (e.g., "US", "CA")
  • timezone: IANA timezone (e.g., "America/New_York")

Features:

• Native Integration: Uses Claude's built-in web search capability
• AI Summaries: Provides comprehensive summaries with citations
• Domain Filtering: Control which sites to include or exclude
• Localization: Get location-specific search results
• No External APIs: Requires only your Anthropic API key

Utility Tools

list_agents

Get list of available AI agents and their capabilities.

{
  "name": "list_agents",
  "arguments": {
    "include_status": true
  }
}

list_workflows

Get list of available workflows and their descriptions.

{
  "name": "list_workflows",
  "arguments": {
    "include_details": true
  }
}

health_check

Check the health status of IRISeller services and agents.

{
  "name": "health_check",
  "arguments": {
    "detailed": true
  }
}

Integration Examples

Claude Desktop Integration

Option 1: NPX (Recommended)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "iriseller": {
      "command": "npx",
      "args": ["@iriseller/mcp-server@latest", "--email", "your-email@company.com", "--password", "your-password", "--api-url", "https://beta.iriseller.com"],
      "env": {
        "JWT_SECRET": "your-jwt-secret-here"
      },
      "disabled": false,
      "autoApprove": ["qualify_lead", "query_crm", "research_company"]
    }
  }
}

Option 2: Global Installation

{
  "mcpServers": {
    "iriseller": {
      "command": "iriseller-mcp-server",
      "args": ["--email", "your-email@company.com", "--password", "your-password"],
      "env": {
        "IRISELLER_API_URL": "https://beta.iriseller.com",
        "JWT_SECRET": "your-jwt-secret-here"
      }
    }
  }
}

Option 3: Local Development

{
  "mcpServers": {
    "iriseller": {
      "command": "node",
      "args": ["/path/to/IRISeller/packages/mcp-server/dist/index.js"],
      "env": {
        "IRISELLER_API_URL": "http://localhost:3001",
        "CREWAI_API_URL": "http://localhost:8001",
        "DEBUG": "false"
      }
    }
  }
}

Custom Application Integration

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['path/to/mcp-server/dist/index.js']
});

const client = new Client({
  name: 'my-app',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Qualify a lead
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'qualify_lead',
    arguments: {
      contact_name: 'John Smith',
      company_name: 'TechCorp Inc'
    }
  }
});

Error Handling

The MCP server provides detailed error information:

{
  "error": {
    "code": -32602,
    "message": "Invalid params: contact_name and company_name are required"
  }
}

Common error codes:

• -32601: Method not found (unknown tool)
• -32602: Invalid params (validation failed)
• -32603: Internal error (service unavailable)

Development

Project Structure

src/
├── types/           # TypeScript type definitions
├── services/        # API service integrations
├── handlers/        # Tool request handlers
├── tools/           # MCP tool definitions
└── index.ts         # Main server implementation

Building

npm run build

Testing

# Run the server in debug mode
DEBUG=true npm run dev

# Test with a simple tool call
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm run dev

Adding New Tools

1. Define the tool in src/tools/index.ts
2. Add the handler in src/handlers/tool-handlers.ts
3. Update types if needed in src/types/index.ts
4. Test the new tool

Troubleshooting

Common Issues

1. Service Connection Errors

   • Ensure IRISeller backend is running on port 3001
   • Ensure CrewAI service is running on port 8001
   • Check network connectivity

2. Authentication Errors

   • Verify API keys in environment variables
   • Check JWT token configuration

3. Tool Execution Timeouts

   • AI agents may take 30-60 seconds for complex operations
   • Increase timeout settings if needed

Debug Mode

Enable debug logging:

DEBUG=true npm run dev

This will show:

• API requests and responses
• Tool execution details
• Service health checks

License

MIT License - see LICENSE file for details.

Support

For support and questions:

• Check the IRISeller documentation
• Review the MCP protocol specification
• Open an issue in the repository