Atomic CRM MCP Server

Atomic CRM MCP Server

An MCP (Model Context Protocol) server for Atomic CRM. It enables an agent (e.g. ChatGPT, Claude, etc.) to read and write data to your Atomic CRM instance securely.

• OAuth 2.1 authentication with Supabase
• Adds a query tool for executing SQL against CRM database
• Row Level Security (RLS) automatically enforced

Supported MCP Clients

• ChatGPT
• Claude.ai
• Visual Studio Code
• Claude Desktop
• Claude Code
• Cursor
• Goose
• Codex CLI
• Gemini CLI
• Gemini Mobile
• ChatGPT Desktop
• ChatGPT Mobile

Installation

MCP Server Setup

1. Clone the repository:

   git clone https://github.com/marmelab/atomic-crm-mcp
   cd your-repo
   

2. Install dependencies:

   npm install
   

3. Add a config file

   cp .env.example .env
   

Supabase Setup

1. Open the Supabase Dashboard

   • Go to https://supabase.com/dashboard and select your project (or create a new one)

2. Enable OAuth 2.1 Server

   • Go to Authentication → OAuth Server
   • Click on Enable the Supabase OAuth Server
   • Set the Authorization Path to /#/oauth/consent
   • Enable the Allow Dynamic OAuth Apps option
   • and save changes

3. Configure asymmetric JWT signing

   • Go to Project Settings → JWT Keys
   • On the JWT Signing Keys tab, if you see an invite to Start using JWT signing keys, this means you're currently using Legacy JWT secret, so click on the Migrate JWT secret button
   • If the current key is of type "Legacy HS256 (Shared Secret)", click on the Rotate keys to use the new key of type "ECC (P256)" or similar

4. Get your Supabase URL

   • Go to Project Settings → Data API
   • Find your Project URL (e.g., https://mrubnlemopavyqvjjwmw.supabase.co)
   • Add it to your .env file as SUPABASE_URL

5. Get your database connection string

   • Go to Project Settings → Database
   • On the top app bar, click on the Connect button
   • Copy the Direct Connection string (it will have [YOUR-PASSWORD] placeholder)
   • Add it to your .env file as DATABASE_URL
   • Replace [YOUR-PASSWORD] with your database password. If you don't know it, go to Database → Settings and reset the password.

Local MCP Server

You can run the MCP server locally if you use a service like ngrok. You will need to choose a publicly accessible HTTPS URL for the MCP server, e.g., https://atomiccrmmcp.ngrok.dev. We'll name this URL MCP_URL in the instructions below.

Run the server with the custom URL:

npm run dev -- --url=MCP_URL

Then, start ngrok in a separate terminal with the same URL:

ngrok http --url MCP_URL 3000   

Now the MCP server is accessible at the ngrok URL.

Hosted MCP Server

Deploy the MCP server to a hosting provider of your choice. Make sure to set the environment variables from your .env file in the hosting provider's settings.

Note that the host must support IPV6, as Supabase Direct Database connection doesn't support IPV4. This expludes IPV4-only providers like Vercel or GitHub actions.

Adding the MCP server to Chat GPT

Note: Atomic CRM MCP works both on the web and mobile versions of ChatGPT. You need a paid Chat GPT account to use custom connectors.

1. Enable the Developer Mode in Settings → Apps → Advanced settings
2. Then, under Settings → Apps, click on the Create button
3. Fill in the fields as follows:
   • Name: Atomic CRM
   • MCP Server URL: (your MCP Server URL, e.g., MCP_URL/mcp)
   • Authentication: OAuth
   • Check the "I understand and want to continue" checkbox
4. Click "Create"
5. A browser window opens for you to authenticate to Atomic CRM and allow access to Claude Code.
6. Once authenticated, you can start using the Atomic CRM extension in Chat GPT

If you're on a workspace or organization account, you need to ask your admin to add and approve the custom connector before you can use it.

Adding the MCP server to Claude.ai

Note: Atomic CRM MCP works both on the web and mobile versions of Claude.You need a paid Claude.ai account to use custom connectors.

1. Open Claude.ai and open the Settings → Connectors page
2. Then click on "Add custom connector"
3. Fill in the fields as follows:
   • Name: Atomic CRM
   • MCP Server URL: (your MCP Server URL, e.g., MCP_URL/mcp)
4. Click "Add"
5. A browser window opens for you to authenticate to Atomic CRM and allow access to Claude Code. 6