outreach-crm-mcp

An outreach CRM that is both a local web application and a Model Context Protocol (MCP) server, so the same contact database can be worked by hand in a browser or driven by an AI assistant through tools.

It ingests contact and company exports (Apollo, Crunchbase, plain CSV/XLSX), fuzzy-matches contacts against company records, ranks them by seniority and fit, drafts personalised emails against a structured event/offer context, scores each draft, and tracks sends and replies through SQLite.

No contact data ships with this repository. See Data and privacy.

Why it is shaped this way

One database, two front ends. The interesting constraint was that outreach is partly judgement and partly bulk work. A web CRM is good for the judgement — reading a company, deciding who to approach. An MCP server is good for the bulk — letting an assistant import a fresh export, re-rank, and draft twenty variants. Both talk to the same SQLite schema, so neither is a second source of truth.

Drafting is separated from scoring, and scoring from sending. templates.ts produces candidate drafts, email-scoring.ts and critic-validator.ts grade them independently, and only then does a mail provider get involved. That split exists because a generator asked to grade its own output will approve it.

Field coverage is tracked explicitly. field-tracker.ts records which context fields were available for a draft and which were actually used, and scores coverage. Personalisation that silently falls back to generic copy is the normal failure of this kind of tool, and it is invisible unless you measure it.

Mail providers are pluggable. mail-provider.ts defines the interface; Outlook/Graph and Gmail implement it behind provider-registry.ts. Credentials are encrypted at rest via token-crypto.ts.

Related MCP server: leadforge

Architecture

Apollo / Crunchbase / CSV export
          │
          ▼
  import.ts · import_crunchbase.ts      normalise, dedupe
          │
          ▼
  join.ts                               fuzzy company↔contact matching
          │
          ▼
  rank.ts · title-utils.ts              seniority + fit ranking
          │
          ▼
  templates.ts ──► email-scoring.ts ──► critic-validator.ts
   (3 drafts)       (1–10 score)          (independent check)
          │
          ▼
  provider-registry.ts ──► outlook-provider.ts / gmail-provider.ts
          │
          ▼
  tracker.ts · replies.ts · report.ts   sends, replies, reporting
          │
          ▼
  SQLite (schema.sql)  ◄── web-server.ts (browser CRM)
                       ◄── index.ts      (MCP server)

Quick start

npm install
cp .env.example .env        # then fill it in
npm run build

# load the synthetic sample so there is something to look at
npm run import -- samples/contacts.sample.csv

npm run web                 # browser CRM
npm start                   # MCP server (stdio)

SETUP.md covers configuration in detail; HOW_TO_USE.md covers day-to-day use.

Data and privacy

This repository contains no real contact data. It was extracted from a working system whose database held real people, and none of that — not the exports, not the SQLite file, not the git history containing them — is included here. This is a fresh repository with no prior history.

samples/contacts.sample.csv is entirely invented: ten fabricated people at six fabricated companies, all on example.com, all with +1-555-01xx numbers. It exists so the importer and the UI have something to render.

.gitignore blocks *.csv, *.xlsx, *.docx and *.db precisely so a real export cannot be committed by accident, with a single narrow exception for samples/. If you point this at a real contact list, that list is personal data. Handle it accordingly — keep it out of version control, and respect the applicable rules on contacting people who did not ask to hear from you.

Event context

The drafting layer personalises against a structured "event context" — dates, venue, themes, attendee types, a default call to action, compliance rules. In this codebase that context is named for the event it was originally built around (earthx_context in the schema, earthx_* fields in the draft types). The shape is general; only the naming is specific. Populate it for your own event or offer via import_earthx.ts / the import_earthx_context MCP tool, or the EVENT_* variables in .env.template.

Layout

• src/ — 42 TypeScript modules: MCP server, web server, import, ranking, drafting, scoring, providers, tracking

• public/ — browser CRM front end

• schema.sql — SQLite schema

• azure/ — Bicep template and deployment scripts

• scripts/ — helper scripts

• samples/ — synthetic sample data

Status

Working, and shaped by real use, but published as a reference implementation rather than a maintained product. Deployment files are included as written; the account-specific values have been replaced with placeholders, so they will need your own.

MIT licensed.