CRM

You have a production-ready MCP server for Customer Relationship Management that is built with TypeScript and SQLite. It exposes a set of CRM-focused tools via the MCP protocol so you can manage contacts, organizations, contact history, todos, data exports, and more with reliable, isolated database operations. This guide shows you how to install, configure, and start using the CRM MCP server in practical steps.

How to use

Start by running the CRM MCP server locally or in your deployment environment. You will connect an MCP client to the server to perform actions such as adding contacts, recording contact history, creating todos, filtering by organization, exporting data to CSV, and viewing recent activities. Use the client to issue named operations (for example, add_contact, search_contacts, add_contact_entry, add_todo, and export_* commands) and pass the required parameters through the client’s arguments. Your workflows may include creating a contact, associating it with an organization, logging interactions, planning next steps with todos, and periodically exporting CRM data for reporting.

Key usage patterns to consider:

• Create and update contacts with essential fields like name, organization, email, and notes.
• Attach interactions to a contact as entries to build a complete history.
• Manage action items for follow-ups via todos and filter them by contact or completion status.
• Export data to CSV for reporting or offline analysis, including both contacts and their history.

How to install

Prerequisites: you need Node.js 18 or newer and npm or yarn installed on your system.

# 1) Clone the CRM MCP project (replace with your actual repository URL)
git clone <repository-url>
cd mcp-crm

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

# 4) Start the CRM MCP server
npm run start:crm

Configuration and usage notes

MCP integration is configured by adding a server entry to your MCP client configuration. You specify how to run the CRM MCP server from your environment so clients can connect and operate against the CRM data.

Here is the example MCP client configuration shown for the CRM server. Use the exact values in your environment if you are setting up the same server locally.

{
  "mcpServers": {
    "mcp_crm": {
      "command": "node",
      "args": ["./build/crm-server.js"],
      "cwd": "/path/to/mcp-crm"
    }
  }
}

Database and maintenance

The CRM uses a SQLite database stored at data/crm.sqlite. The system creates the database and tables automatically on first run. Archives and backups live under data/archives and are kept separate from your version control.

Key maintenance tasks include resetting the database (which archives the current state and creates a fresh one), archiving the current database, listing archives, showing statistics, and managing contact entries.

# Reset database (archive current, create fresh)
npm run db:reset

# Archive current database (backup without reset)
npm run db:archive

# List all archived databases
npm run db:list

# Show current database statistics
npm run db:stats

# Basic entry management commands
npm run db:list-entries        # List all contact entries
npm run db:view-entry 1        # View detailed entry
npm run db:delete-entry 1      # Delete entry by ID

Security and reliability

You get input validation, parameterized queries to prevent SQL injection, and sanitization to guard against XSS. All operations archive data before making changes, and restore operations back up the current state first. This design provides a zero-data-loss guarantee for backups and restores and ensures you can recover from any change.

Testing and quality

The project includes a comprehensive 3-phase testing strategy with database isolation. Run the full suite to verify infrastructure, core CRM features, and quality assurance checks before deploying to production.

# Comprehensive test suite (recommended) - uses database isolation
npm run test:comprehensive

# Individual test phases
npm run test:db
cd tests && npx tsx run-phase-b-tests.ts
cd tests && npx tsx run-phase-c-tests.ts

Available tools

add_contact

Create a new contact with fields such as name, organization, job_title, email, phone, and notes.

update_contact

Update an existing contact using id and optional fields like name, organization, job_title, email, phone, notes.

get_contact_details

Retrieve detailed information for a specific contact by id.

list_contacts

List all contacts with an optional flag to include archived contacts.

search_contacts

Search contacts by name, email, or organization using a query string.

list_contacts_by_organization

Filter and list contacts belonging to a specific organization.

archive_contact

Archive a contact to perform a soft delete.

add_contact_entry

Add an interaction history entry for a specific contact with type, subject, and content.

update_contact_entry

Update an existing contact entry identified by entry_id.

get_contact_history

Get all history entries for a specific contact, with an optional limit.

get_recent_activities

Retrieve recent CRM activities with an optional limit.

add_todo

Create a todo item for a contact with todo_text and optional target_date.

update_todo

Update an existing todo by todo_id with optional todo_text, target_date, and is_completed.

get_todos

Fetch todos with optional filtering by contact_id, completion status, and date ranges.

export_contacts_csv

Export contacts to a CSV file, including optional archived contacts and summaries.

export_contact_history_csv

Export contact history to CSV with optional per-contact filtering.

export_full_crm_csv

Export the complete CRM data to a CSV including todos.

export_todos_csv

Export all todos to a CSV file.