nexus-mcp

An MCP (Model Context Protocol) server that exposes a real sales CRM as tools an AI agent can call — plus a CLI that does the same job with no model involved.

Built to solve an actual problem, not as an exercise. I run a small web-development studio and my CRM had grown to ~270 prospects with long free-text notes that nobody re-read. Prospects who had shown interest were quietly dying in the list, because a spreadsheet only shows you what you remember to look for. The first time I ran this, it surfaced two leads I had abandoned a week earlier.

$ nexus-crm hoy

VENCIDOS (1)
────────────
#a3f21c08-4d19-4b7e-9e02-6c1f8b40d772 Estudio Ferrari & Asoc. · Legal · Zárate [Respondió]
    contacto: contacto@ferrari.example.com · seguir: 2026-07-24 · $450000
    vencido hace 3 día(s)

ABANDONADOS — nadie les puso fecha (4)
──────────────────────────────────────
#7b90e4d1-2c53-49aa-8f61-0d5e7a3c9b14 Odontología Norte · Salud · Zárate [Respondió]
    contacto: +54 9 3487 000002 · $590000
...

The output above comes from demo/seed.sql — invented businesses, invented phone numbers, reserved example.com domains. No client data lives in this repository.

The five tools

Tool	What it does
buscar_prospectos	Free-text search across name, industry, area, contact and notes, with optional filters by status/industry/area
resumen_pipeline	Pipeline snapshot: count per status, overdue follow-ups, abandoned leads, total value at stake
seguimientos_pendientes	Who to chase: overdue, upcoming, and abandoned — interested, not discarded, and with no follow-up date set
cambiar_estado	Move a prospect along the pipeline
agregar_nota	Append a dated entry to the prospect's history, in the same format the CRM's own UI writes

The third one is the reason this exists. Overdue follow-ups are easy — any list view shows them. Leads with no date at all are invisible by construction, and those are the ones that cost money.

Stack

TypeScript · Node 22 · @modelcontextprotocol/sdk · Supabase (PostgreSQL) · Zod

Tool inputs are validated with Zod schemas, so the model gets a typed contract and a useful error instead of a silent failure. The server speaks MCP over stdio, which is what desktop MCP clients expect.

Row-level security

The prospectos table has RLS enabled. Worth knowing, because it fails quietly: with the publishable key alone, Supabase returns an empty list rather than an error — so the tools look like they work and report zero results.

The server signs in with email/password before its first query and holds an authenticated session, which is what the RLS policy checks. Credentials live in .env, never in the repo.

Running it

npm install
cp .env.example .env    # fill in your Supabase project and login
npm run build

As a CLI:

node dist/cli.js hoy
node dist/cli.js resumen
node dist/cli.js buscar odonto
node dist/cli.js estado 42 "Respondió"
node dist/cli.js nota 42 "resent the quote, he'll look at it this week"

As an MCP server, add it to your client's config:

{
  "mcpServers": {
    "nexus-crm": {
      "command": "node",
      "args": ["/absolute/path/to/nexus-mcp/dist/server.js"]
    }
  }
}

Then ask in plain language: "who should I follow up with today?", "mark Ferrari as replied and note that he asked for the quote again".

Trying it without my data

demo/seed.sql creates the table, its RLS policy and 15 fictional prospects — invented names, phone numbers and negotiation notes. Run it in an empty Supabase project, point your .env at it, and everything below works against that instead.

What this is not

It doesn't replace the CRM and it doesn't collect data on its own. It's a query-and-update layer on top of a database that already existed. The CRM UI stays the place where records are created; this is for the question a UI is bad at answering: what am I forgetting?

License

MIT