Medicus CRM MCP Server

A Model Context Protocol (MCP) server for the Medicus CRM system, supporting both local STDIO and remote HTTP access.

Features

• 18 CRM tools for managing companies, contacts, and related data
• Supabase integration for data persistence
• Local STDIO transport for development (full functionality)
• Remote HTTP transport for production deployment (tool listing + basic protocol)
• Token-based authentication for security

Local Development

Prerequisites

• Node.js 18+
• Supabase project with service role key

Setup

1. Install dependencies:

   npm install
   

2. Create environment file:

   cp env.example .env.local
   

3. Configure your environment variables in .env.local:

   SUPABASE_URL=your_supabase_url_here
   SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key_here
   MCP_TOKEN=your_long_random_token_here
   

Running Locally

STDIO Mode (for local MCP clients)

npm run mcp:stdio

HTTP Mode (for testing remote access)

npm run dev

Then test with MCP Inspector:

npx @modelcontextprotocol/inspector http://localhost:3000/api/mcp?token=your_token

Note: The HTTP endpoint currently supports tool listing and basic MCP protocol. For full tool execution, use the STDIO mode locally.

Deployment to Vercel

1. Install Vercel CLI:

   npm i -g vercel
   

2. Deploy:

   vercel
   

3. Set environment variables in Vercel dashboard:

   • SUPABASE_URL
   • SUPABASE_SERVICE_ROLE_KEY
   • MCP_TOKEN (optional)

4. Your MCP server will be available at:

   https://your-app.vercel.app/api/mcp?token=your_token
   

Adding to Claude

In Claude Desktop or Web:

1. Go to Settings → Connectors
2. Add custom connector
3. Enter your Vercel URL: https://your-app.vercel.app/api/mcp?token=your_token

Tool Registration

The main tool registration logic is in lib/register-crm-tools.js. This file contains:

• Helper functions for error handling and data manipulation
• All 18 CRM tool registrations
• Supabase integration logic

To add new tools or modify existing ones, edit this file. The changes will be available in both STDIO and HTTP modes.

Security

• The server uses Supabase service role key for database access
• Optional token-based authentication prevents unauthorized access
• For production, consider implementing OAuth instead of simple tokens

Architecture

├── lib/
│   ├── register-crm-tools.js    # Shared tool registration logic
│   └── supabase.js              # Supabase client factory
├── bin/
│   └── stdio.mjs                # Local STDIO server
├── app/
│   └── api/
│       └── mcp/
│           └── route.ts         # HTTP MCP endpoint
└── package.json                 # Dependencies and scripts