headless-crm

Headless CRM exposes a full REST API for managing organizations, people, deals, activities, tasks, and campaigns, together with a dedicated MCP server endpoint that allows AI agents to remotely invoke 17 tools via a JSON-RPC style interface. To connect an MCP client (for example Claude or another agent) you point the client at the MCP endpoint and enable OAuth 2.1 authentication. The MCP server handles authentication, discovery, and token management, so your agent can perform operations like listing organizations, creating deals, or logging activities through the 17 available tools. Typical workflows involve either wiring in via Claude with the provided transport bridge or configuring .mcp.json in your agent to reference the headless-crm MCP endpoint. The server supports standard HTTP transport for MCP with Bearer token authentication after the OAuth flow completes.

Prerequisites:

• Node.js 20+ (for local development of the surrounding app) or a hosting environment compatible with the deployed MCP server setup
• PostgreSQL database
• Git

Setup steps:

1. Clone the repository git clone https://github.com/AlexisLaporte/headless-crm.git cd headless-crm

2. Install dependencies npm install

3. Configure environment cp .env.example .env # Edit with your credentials (DB connection, OAuth settings, etc.)

4. Prepare the database npm run db:push # Creates database tables

5. Development run (local) ./dev/start.sh # Starts Vite frontend and API (typical local dev ports)

6. Production build and run npm run build npm run start:server # Starts API server (port 3002)

Note: The frontend is served as static files by nginx in production, with /api and /.well-known/oauth proxied to the backend.

Key points and tips:

• The MCP endpoint is authenticated using OAuth 2.1 with dynamic client registration. On first use, a browser window will prompt Google SSO for consent.
• No separate API token is needed for MCP; the client uses bearer tokens obtained via the OAuth flow.
• The MCP server exposes 17 tools across categories such as Organizations, People, Deals, Activities, and Tasks. Use the MCP JSON-RPC interface at /api/mcp to invoke them.
• For development, ensure PostgreSQL is running and the database is migrated via npm run db:push. The dev script starts both the frontend server (Vite at :5173) and the API server (at :5172).
• If you’re integrating with Claude or another agent, use the provided connect command or add an entry to .mcp.json as shown in the README: { "mcpServers": { "headless-crm": { "type": "http", "url": "https://headless-crm.tuls.me/api/mcp" } } }
• The MCP transport uses Streamable HTTP, and the API endpoints require proper CORS and OAuth flow configuration in production.