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

Install dependencies:
```
npm install
```
Create environment file:
```
cp env.example .env.local
```

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

Install Vercel CLI:
```
npm i -g vercel
```
Deploy:
```
vercel
```
Set environment variables in Vercel dashboard:
- SUPABASE_URL
- SUPABASE_SERVICE_ROLE_KEY
- MCP_TOKEN (optional)

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:

Go to Settings → Connectors
Add custom connector
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

Local Development

Prerequisites

Node.js 18+

Supabase project with service role key

Setup

Install dependencies:

npm install

Create environment file:

cp env.example .env.local

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.

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.

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