README.md
A production-ready MCP server for CRM built with TypeScript and SQLite.
CRM MCP Server
A production-ready Model Context Protocol (MCP) server for Customer Relationship Management (CRM) functionality, built with TypeScript and SQLite.
š Features
Core CRM Tools (18 Total)
- Contact Management: Add, update, search, list, and archive contacts
- Organization Management: Filter contacts by organization
- Contact History: Track, update, and manage interactions, calls, emails, meetings, and notes
- Entry Management: Full CRUD operations on contact history entries
- Todo Management: Add, update, filter, and track action items for contacts
- Data Export: CSV exports for contacts, history, and full CRM data
- Recent Activities: Track and retrieve recent CRM activities
Technical Excellence
- ā 100% Test Coverage - Comprehensive 3-phase test suite with database isolation
- ā Production Ready - Robust error handling and input validation
- ā High Performance - Optimized for bulk operations and large datasets
- ā Security Focused - SQL injection protection and input sanitization
- ā Edge Case Handling - Thoroughly tested boundary conditions
- ā Database Management - Safe archive/restore system with zero data loss
- ā Entry Management - Complete contact history CRUD with database scripts
- ā Modular Testing - Isolated test phases with automatic state management
š¦ Installation
Prerequisites
- Node.js 18+
- npm or yarn
Setup
# Clone the repository
git clone <repository-url>
cd mcp-crm
# Install dependencies
npm install
# Build the project
npm run build
# Start the server
npm run start:crm
š§ Configuration
MCP Integration
Add to your .cursor/mcp.json or MCP client configuration:
{
"mcpServers": {
"mcp-crm": {
"command": "node",
"args": ["./build/crm-server.js"],
"cwd": "/path/to/mcp-crm"
}
}
}
Database
- Location:
data/crm.sqlite - Type: SQLite 3
- Auto-created: Database and tables are automatically initialized
- Git Ignored: Database files and archives are excluded from version control for security and size reasons
šļø Database Management
The CRM system includes powerful database management commands for safely resetting, archiving, and restoring your data.
Quick Commands
# 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
# Contact entry management
npm run db:list-entries # List all contact entries
npm run db:list-entries 1 # List entries for contact ID 1
npm run db:list-entries "" 10 # List 10 most recent entries (all contacts)
npm run db:view-entry 1 # View detailed entry
npm run db:delete-entry 1 # Delete entry by ID
npm run db:update-entry 1 content "Updated content" # Update entry field
# Show help for database commands
npm run db:help
Detailed Usage
Reset Database
Safely archives your current database and creates a fresh empty one.
# Basic reset
npm run db:reset
# Reset with reason (helpful for tracking)
npm run db:reset cleanup
npm run db:reset "testing-new-features"
What happens:
- š¦ Current database is archived with timestamp
- šļø Current database is removed
- ā Fresh empty database is created
- š”ļø Your data is safely preserved in archives
Archive Database
Create a backup without resetting (keeps current database).
# Basic archive
npm run db:archive
# Archive with reason
npm run db:archive "before-major-update"
List Archives
View all your database backups.
npm run db:list
Example output:
š¦ Database Archives
==================================================
š crm-backup-2025-06-04T19-15-35-cleanup.sqlite
Created: 6/4/2025, 7:15:35 PM
Size: 45.32 KB
Path: /data/archives/crm-backup-2025-06-04T19-15-35-cleanup.sqlite
š crm-backup-2025-06-03T14-22-18.sqlite
Created: 6/3/2025, 2:22:18 PM
Size: 42.17 KB
Path: /data/archives/crm-backup-2025-06-03T14-22-18.sqlite
Restore from Archive
Restore a previous database from archive.
npm run db:list # First, see available archives
# Then restore specific archive (replace with actual filename):
npx tsx scripts/database-manager.ts restore crm-backup-2025-06-04T19-15-35.sqlite
What happens:
- š¦ Current database is archived (safety backup)
- š Selected archive is restored as current database
- ā Your data is back to the archived state
Database Statistics
Check your current database status.
npm run db:stats
Example output:
š Current Database Statistics
==================================================
Contacts: 546
Entries: 1,234
Size: 45.32 KB
Contact Entry Management
Manage contact history entries with full CRUD operations.
# List
Tools (7)
contact_managementAdd, update, search, list, and archive contacts.organization_managementFilter contacts by organization.contact_historyTrack, update, and manage interactions, calls, emails, meetings, and notes.entry_managementFull CRUD operations on contact history entries.todo_managementAdd, update, filter, and track action items for contacts.data_exportCSV exports for contacts, history, and full CRM data.recent_activitiesTrack and retrieve recent CRM activities.Configuration
claude_desktop_config.json
{
"mcpServers": {
"mcp-crm": {
"command": "node",
"args": ["./build/crm-server.js"],
"cwd": "/path/to/mcp-crm"
}
}
}Try it
āAdd a new contact named John Doe from Acme Corp with his email and phone number.
āShow me the recent interaction history for the contact with ID 1.
āCreate a todo item to follow up with Sarah Jenkins next Tuesday regarding the contract.
āExport all my CRM contacts and interaction history to a CSV file.
āSearch for all contacts associated with the organization 'TechFlow Inc'.