Atomic Crm MCP

🚀 Atomic CRM MCP Server

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

✨ Features

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

📦 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 the 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, it means you're currently using the Legacy JWT secret. Click on the Migrate JWT secret button.
   • If the current key is of type "Legacy HS256 (Shared Secret)", click on 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 the [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 need to choose a publicly accessible HTTPS URL for the MCP server, e.g., https://atomiccrmmcp.ngrok.dev. We'll refer to this URL as MCP_URL in the following instructions.

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 the Supabase Direct Database connection doesn't support IPV4. This excludes IPV4-only providers like Vercel or GitHub actions.

💻 Usage Examples

Adding the MCP server to Chat GPT

Note: Atomic CRM MCP works on both 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 on both 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. Once authenticated, you can start using the Atomic CRM extension in Chat GPT.

Adding the MCP server to Visual Studio Code

1. Open the command palette (Ctrl+Shift+P or Cmd+Shift+P) and run the "MCP: Add Server..." command.
2. In the dropdown listing MCP types, choose "HTTP".
3. Enter the MCP server URL (e.g., MCP_URL/mcp) when prompted.
4. Name this server atomic-crm when prompted.
5. Choose "Global" or "Local" scope as desired.
6. A Dialog opens for you to authenticate to Atomic CRM and allow access. Click "Allow".
7. A browser window opens for you to authenticate to Atomic CRM and allow access to Claude Code.
8. Once authenticated, you can start using the Atomic CRM extension in Visual Studio Code.

Adding The MCP Server To Claude Desktop

1. Navigate to Settings > Extensions on Claude Desktop.
2. Click on "Add a custom Extension".
3. Fill in the fields as follows:
   • Name: Atomic CRM
   • URL: (your MCP Server URL, e.g., MCP_URL/mcp)
4. Click "Add".
5. The new extension should now appear in your list of extensions. Click on "Connect" to start using it.
6. A browser window opens for you to authenticate to Atomic CRM and allow access to Claude.
7. Once authenticated, you can start using the Atomic CRM extension in Claude.

Adding the MCP server to Claude Code

1. Add the Atomic CRM MCP server to Claude Code by running the following command in your terminal:

   claude mcp add atomic-crm --transport http MCP_URL/mcp
   

2. Open Claude Code:

   claude
   

3. List the available MCP servers:

   /mcp
   

4. The atomic-crm server should appear as "needs authentication". Press Enter to authenticate.

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 Claude Code.

🔧 Technical Details

MCP Tools

• get_schema: Retrieves the database schema to help construct accurate SQL queries, including foreign key relationships for JOINs.
• query: Executes SQL queries against the CRM database with RLS enforcement. Supports complex queries including JOINs.

Security

• JWT Validation: All tokens are validated against Supabase JWKS.
• RLS Enforcement: Queries run with the user's JWT, and auth.uid() is available in SQL.
• Session Management: Cryptographically secure session IDs.
• HTTPS Required: Must use HTTPS in production.
• Token Storage: Tokens are only kept in memory and are never logged.

OAuth Flow

1. The MCP client connects without authentication → The server returns 401 with the Protected Resource Metadata URL.
2. The client discovers OAuth endpoints from the Protected Resource Metadata.
3. The client fetches Supabase's OpenID Connect configuration.
4. The user authenticates via Supabase (your Atomic CRM auth UI).
5. The client receives a JWT access token.
6. The client makes authenticated MCP requests with a Bearer token.
7. The server validates the JWT against Supabase JWKS.
8. The server executes queries using the user's JWT for RLS enforcement.

📚 Documentation

Troubleshooting

Connection to the MCP Server Fails

• Ensure Supabase uses JWT Signing Keys (RS256) instead of JWT Signing Keys (HS256) (go to the Supabase dashboard > Settings > JWT Keys). The current key should NOT use the "Legacy HS256 (Shared Secret)" type, but something like "ECC (P256)".

JWT Validation Fails

• Verify that Supabase is configured for asymmetric JWT signing (RS256).
• Check that SUPABASE_URL matches the token's iss claim.
• Ensure OAuth 2.1 is enabled in the Supabase dashboard.

Database Connection Failed

• "Tenant or user not found": Your connection string format is incorrect. For direct connection, use:
  • postgresql://postgres:PASSWORD@db.PROJECT-REF.supabase.co:5432/postgres
  • NOT the pooler format with postgres.PROJECT-REF or port 6543.
• Verify that DATABASE_URL is correct and accessible.
• Ensure you've replaced [YOUR-PASSWORD] with your actual database password.
• Check firewall rules to allow connections from your server.

RLS Blocking Queries

• Check RLS policies to allow access for the authenticated user.
• Verify that auth.uid() matches the expected user ID.
• Test with a service role key to bypass RLS (for development only).

📄 License

ISC

🤝 Contributing

## run in development mode
npm run dev
## build for production
npm run build
npm start
## typecheck
npm run typecheck

📖 References

• MCP Specification
• MCP Authorization
• Supabase OAuth Server
• RFC 9728 - OAuth Protected Resource Metadata