mcp-server-crm by zeeshan8281 - MCP Server

🚀 Real MCP Server - CRM Assistant with AI Intelligence

A complete Model Context Protocol (MCP) server implementation for CRM operations with advanced AI features

📋 What is This?

This is a real MCP server that implements the Model Context Protocol specification. It provides AI-powered CRM functionality through standardized MCP tools that can be used by AI agents, Cursor, and other MCP-compatible clients.

Key Features:

✅ Real MCP Server - Follows Model Context Protocol specification
🧠 AI-Powered Analytics - Revenue prediction, contact scoring, relationship mapping
🔌 MCP Tool Integration - 10 comprehensive tools for CRM operations
📊 Advanced Insights - Company analysis, trend detection, smart recommendations
💬 AI Chat Interface - Natural language queries for CRM data
🕸️ Relationship Mapping - Visual network of contact connections

🏗️ Architecture

MCP Server Components:

┌─────────────────────────────────────────────────────────────┐
│                    MCP Server Layer                        │
├─────────────────────────────────────────────────────────────┤
│  • ListToolsRequestSchema  • CallToolRequestSchema         │
│  • StdioServerTransport    • Server Instance               │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  AI Analytics Engine                        │
├─────────────────────────────────────────────────────────────┤
│  • Revenue Prediction      • Contact Scoring               │
│  • Relationship Mapping    • Smart Recommendations         │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Supabase Backend                        │
├─────────────────────────────────────────────────────────────┤
│  • PostgreSQL Database     • Real-time Subscriptions       │
│  • Row Level Security     • API Authentication            │
└─────────────────────────────────────────────────────────────┘

🛠️ Setup & Installation

1. Prerequisites

Node.js 18+
Supabase account and project
MCP-compatible client (Cursor, Claude Desktop, etc.)

2. Install Dependencies

npm install

3. Environment Setup

Create .env file:

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key

# Optional: Server Configuration
PORT=3000

4. Database Setup

Create the contacts table in Supabase:

CREATE TABLE contacts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT NOT NULL,
  company TEXT,
  revenue INTEGER DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE contacts ENABLE ROW LEVEL SECURITY;

-- Create policy for public access (adjust as needed)
CREATE POLICY "Allow public access" ON contacts FOR ALL USING (true);

🔧 MCP Tools Available

Core CRM Operations

get_contacts - Retrieve contacts with AI scoring
add_contact - Add new contact with AI insights
get_top_clients - Get top clients by revenue
search_contacts - Search contacts by name/email

AI-Powered Analytics

get_ai_insights - Comprehensive AI analytics
predict_revenue - AI revenue prediction for contacts
get_relationship_map - Network visualization data
get_analytics - Detailed performance metrics
get_recommendations - AI-powered action suggestions

Natural Language Interface

ai_chat - Chat with AI assistant for CRM queries

🚀 Usage Examples

Using with Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "crm-assistant": {
      "command": "node",
      "args": ["/path/to/crm-mcp/server.js"],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_KEY": "your-supabase-key"
      }
    }
  }
}

Tool Usage Examples

Get Contacts with AI Scoring

// MCP Tool Call
{
  "name": "get_contacts",
  "arguments": {
    "limit": 10
  }
}

Add Contact with AI Insights

// MCP Tool Call
{
  "name": "add_contact",
  "arguments": {
    "name": "John Doe",
    "email": "john@techcorp.com",
    "company": "TechCorp",
    "revenue": 15000
  }
}

AI Chat Interface

// MCP Tool Call
{
  "name": "ai_chat",
  "arguments": {
    "message": "Who are my top 5 tech clients?"
  }
}

🧠 AI Features Deep Dive

Revenue Prediction Algorithm

// Factors considered:
- Company size (length > 10 chars = 1.5x multiplier)
- Email domain (business vs personal)
- Name length (longer names = higher potential)
- Current revenue (base for prediction)

// Formula:
basePrediction = currentRevenue * 1.2
multiplier = companySize * emailDomain * nameLength
predictedRevenue = basePrediction * multiplier

Contact Scoring System (0-100 scale)

// Scoring breakdown:
- Revenue Factor: 40% weight (max 40 points)
- Company Factor: 30% weight (tech companies get bonus)
- Email Domain: 20% weight (business domains preferred)
- Name Length: 10% weight (longer names = higher score)

Relationship Mapping

// Connection types detected:
- Colleague: Same company (strength: 0.9)
- Domain: Same email domain (strength: 0.7)
- High-value: Similar revenue ranges (strength: 0.6)
- Tech-network: Both in tech companies (strength: 0.5)
- Strategic: Random connections (strength: 0.3)

📊 AI Chat Capabilities

The AI chat interface understands natural language queries:

Supported Query Types:

Count Queries: "How many contacts do I have?"
Revenue Analysis: "What's my total revenue?"
Top Clients: "Who is my most profitable client?"
Tech Filtering: "Show me my top 10 tech clients"
Analytics: "Give me AI insights on my contacts"
Recommendations: "What should I focus on?"

Example Conversations:

User: "Who is my most profitable person?"
AI: "💰 Your most profitable person is John Smith with $25,000 in revenue!"

User: "Show me my top 5 tech clients"
AI: "🚀 Your top 5 tech clients:
1. Jane Doe - $15,000
2. Bob Wilson - $12,000
3. Alice Brown - $8,500
..."

User: "How many contacts do I have?"
AI: "📊 You have 47 contacts in your CRM!"

🔌 MCP Protocol Implementation

Server Configuration

const server = new Server(
  {
    name: 'crm-assistant-mcp',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

Tool Definition

{
  name: 'get_contacts',
  description: 'Get all contacts from the CRM with AI scoring and insights',
  inputSchema: {
    type: 'object',
    properties: {
      limit: {
        type: 'number',
        description: 'Maximum number of contacts to return (default: 50)',
        default: 50
      }
    }
  }
}

Request Handling

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Tool implementation...
});

🎯 Key Differences from Express API

Feature	Express API	MCP Server
Protocol	HTTP REST	Model Context Protocol
Transport	HTTP/WebSocket	StdioServerTransport
Client Integration	Custom frontend	AI agents, Cursor, Claude
Tool Discovery	Manual documentation	Automatic via ListTools
Error Handling	HTTP status codes	MCP error responses
Data Format	JSON responses	MCP content format

🚀 Running the Server

Development Mode

npm run dev

Production Mode

npm start

Expected Output

🚀 MCP CRM Assistant Server Started! 🚀
🧠 AI Features: Analytics, Predictions, Relationship Mapping
⚡ Real-time: Live updates, notifications, smart insights
🎯 Ready for INSANE CRM operations via MCP!

🔧 Troubleshooting

Common Issues:

"Please set SUPABASE_URL and SUPABASE_KEY"
- Ensure .env file exists with correct values
- Check Supabase project is active
"Unknown tool" errors
- Verify MCP client is properly configured
- Check tool names match exactly
Database connection errors
- Verify Supabase URL and key are correct
- Ensure contacts table exists
- Check RLS policies allow access

Debug Mode

DEBUG=mcp* node server.js

📈 Performance & Scalability

Current Limits:

Contacts: 50 per request (configurable)
Search Results: 50 per query
AI Processing: Real-time (no caching)

Optimization Opportunities:

Implement caching for AI insights
Add pagination for large datasets
Optimize relationship mapping algorithm
Add database indexing

🔮 Future Enhancements

Planned Features:

Real-time Updates: WebSocket integration for live data
Advanced AI: Machine learning models for predictions
Integration APIs: Connect with external CRM systems
Custom Scoring: User-defined scoring algorithms
Bulk Operations: Batch contact operations
Export/Import: Data migration tools

📚 Resources

MCP Documentation:

Supabase Resources:

AI & Analytics:

🤝 Contributing

Fork the repository
Create a feature branch
Implement your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🎉 Conclusion

This MCP server transforms your CRM into an AI-powered intelligence platform. By implementing the Model Context Protocol, it seamlessly integrates with AI agents and development tools, providing powerful CRM operations through a standardized interface.

Ready to revolutionize your CRM with AI? Let's get started! 🚀