crm-mcp-server

sabrewolfai-dev/crm-mcp-server

3.1

If you are the rightful owner of crm-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A minimalistic Model Context Protocol (MCP) Server that integrates with Supabase, Cal.com, Gmail, and Twilio APIs to provide a comprehensive suite of functionalities for database operations, event scheduling, email management, and communication services.

MCP Server with API Integrations

A minimalistic Model Context Protocol (MCP) Server that provides integrations with Supabase, Cal.com, Gmail, and Twilio APIs.

Features

  • Supabase Integration: Database operations (CRUD) via REST API
  • Cal.com Integration: Event scheduling and management
  • Gmail Integration: Send emails and fetch messages
  • Twilio Integration: Send SMS, WhatsApp messages, and make calls
  • MCP Protocol Support: Standardized tool definitions and endpoints
  • Security: Rate limiting, CORS, and Helmet security headers
  • Logging: Winston-based logging with file and console output

Prerequisites

  • Node.js 18.0.0 or higher
  • npm or yarn package manager
  • Accounts and API keys for:
    • Supabase
    • Cal.com
    • Gmail/Google Cloud Console
    • Twilio

Installation

  1. Clone the repository

    git clone <your-repo-url>
cd mcp-server-integrations

  2. Install dependencies

    npm install

  3. Set up environment variables

    cp env.example .env

    Edit .env with your actual API credentials (see Configuration section below).

  4. Create logs directory

    mkdir logs

Configuration

Environment Variables

Copy env.example to .env and configure the following:

Server Configuration
  • PORT: Server port (default: 3000)
  • NODE_ENV: Environment (development/production)
  • LOG_LEVEL: Logging level (error/warn/info/debug)
  • ALLOWED_ORIGINS: Comma-separated list of allowed CORS origins
Supabase
  1. Go to Supabase and create a new project
  2. Get your project URL and anon key from Settings > API
  3. Set SUPABASE_URL and SUPABASE_ANON_KEY
Cal.com
  1. Go to Cal.com and create an account
  2. Generate an API key from Settings > Developer
  3. Set CAL_API_KEY
Gmail/Google
  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable Gmail API
  4. Create OAuth 2.0 credentials
  5. Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI
  6. Get refresh token using OAuth flow (see Gmail Setup section)
Twilio
  1. Go to Twilio Console
  2. Get Account SID and Auth Token from Dashboard
  3. Purchase a phone number
  4. Set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER

Gmail OAuth Setup

To use Gmail API, you need to complete the OAuth flow:

  1. Start the server

    npm run dev

  2. Get authorization URL

    curl http://localhost:3000/api/gmail/auth-url

  3. Visit the URL and authorize the application

  4. Exchange code for tokens

    curl -X POST http://localhost:3000/api/gmail/token \
  -H "Content-Type: application/json" \
  -d '{"code": "YOUR_AUTHORIZATION_CODE"}'

  5. Update .env with the refresh token

Usage

Start the Server

# Development mode with auto-reload
npm run dev

# Production mode
npm start

Health Check

curl http://localhost:3000/health

MCP Tools

Get available tools:

curl http://localhost:3000/api/mcp/tools

API Endpoints

Supabase
# Query database
curl -X POST http://localhost:3000/api/supabase/query \
  -H "Content-Type: application/json" \
  -d '{
    "table": "users",
    "operation": "select",
    "filters": {"active": true}
  }'
Cal.com
# Schedule event
curl -X POST http://localhost:3000/api/cal/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting",
    "startTime": "2024-01-15T10:00:00Z",
    "endTime": "2024-01-15T11:00:00Z",
    "attendees": ["user@example.com"]
  }'

# Get events
curl http://localhost:3000/api/cal/events
Gmail
# Send email
curl -X POST http://localhost:3000/api/gmail/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "recipient@example.com",
    "subject": "Test Email",
    "body": "<h1>Hello World</h1>"
  }'

# Get messages
curl http://localhost:3000/api/gmail/messages
Twilio
# Send SMS
curl -X POST http://localhost:3000/api/twilio/sms \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "message": "Hello from MCP Server!"
  }'

Development

Project Structure

src/
├── server.js          # Main server file
├── services/          # API service integrations
│   ├── supabase.js   # Supabase service
│   ├── cal.js        # Cal.com service
│   ├── gmail.js      # Gmail service
│   └── twilio.js     # Twilio service
└── utils/
    └── logger.js     # Winston logger configuration

Adding New Services

  1. Create a new service file in src/services/
  2. Implement the service class with required methods
  3. Add endpoints to src/server.js
  4. Update MCP tools definition
  5. Add environment variables to env.example

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN mkdir logs
EXPOSE 3000
CMD ["npm", "start"]

Environment Variables for Production

Make sure to set all required environment variables in your production environment:

  • Use strong, unique values for all API keys
  • Set NODE_ENV=production
  • Configure proper ALLOWED_ORIGINS
  • Set up proper logging and monitoring

GitHub Repository Setup

  1. Initialize Git repository

    git init
git add .
git commit -m "Initial commit: MCP Server with API integrations"

  2. Create GitHub repository

    • Go to GitHub and create a new repository
    • Don't initialize with README (we already have one)

  3. Connect local repository to GitHub

    git remote add origin https://github.com/yourusername/your-repo-name.git
git branch -M main
git push -u origin main

  4. Set up GitHub Actions (optional) Create .github/workflows/ci.yml:

    name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test

Security Considerations

  • Never commit .env files to version control
  • Use environment-specific API keys
  • Implement proper rate limiting
  • Validate all input data
  • Use HTTPS in production
  • Regularly rotate API keys

Troubleshooting

Common Issues

  1. Port already in use

    # Change PORT in .env or kill existing process
lsof -ti:3000 | xargs kill -9

  2. API authentication errors

    • Verify API keys are correct
    • Check API quotas and limits
    • Ensure proper OAuth flow for Gmail

  3. CORS errors

    • Add your frontend URL to ALLOWED_ORIGINS
    • Check browser developer tools for specific errors

Logs

Check logs in the logs/ directory:

  • combined.log: All logs
  • error.log: Error logs only

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

  • Check the troubleshooting section
  • Review API documentation for each service
  • Open an issue on GitHub