The Monica CRM MCP Server enables AI assistants to comprehensively manage Monica CRM data through a unified interface, offering contact management, activity tracking, task organization, and relationship management capabilities.
Core Features:
Contact Management - Search, create, update, and delete contacts with full profile management including names, gender, birthdates, contact details, and physical addresses
Activity & Interaction Tracking - Log conversations, phone calls, meetings, and events with contacts, including activity type management and categorization
Task & Reminder System - Create, update, and manage tasks (open/completed status) and reminders with scheduling and recurring nudge capabilities
Relationship Management - Establish and manage relationships between contacts with configurable relationship types and groups
Organization Tools - Create and manage contact groups, tags, and categorization systems for efficient contact organization
Notes & Financial Records - Capture notes, documents, photos, and track gifts/debts associated with contacts
Metadata & System Management - Browse system catalogs for genders, countries, activity types, relationship types, and contact field types with lookup capabilities
Data Streaming - Stream normalized contact profiles and latest notes as resources
Health Monitoring - Verify CRM connectivity and credential validity
Provides comprehensive contact relationship management through Monica CRM's API, including contact search and management, activity tracking, task and reminder scheduling, note capture, relationship mapping, address management, and custom field handling.
Monica CRM MCP Server
A Model Context Protocol (MCP) server that lets assistants such as Claude Desktop read from and write to any Monica CRM instance. It wraps Monica's REST API with a handful of assistant-friendly tools and resources so you can search contacts, inspect timelines, capture notes, and keep on top of tasks without leaving the chat.
Features
Contact search & summaries – find people by name/email and return normalized details with custom fields.
Contact management – create, update, or delete contacts without leaving the assistant.
Contact info management – view contact summaries, update profile details, and manage communication fields/addresses from one tool.
Activity tracking – capture meetings/outings and review recent shared history.
Automatic ID resolution – look up genders, countries, contact field types, activity types, and relationship types by name when executing tools.
Metadata browser – inspect Monica catalogs (genders, countries, activity types, etc.) from one consolidated tool when you need raw IDs.
Stay-on-track actions – create or update tasks and reminders together without juggling multiple tools.
Financial tracking – log Monica gifts and debts through one shared tool.
Relationship management – inspect existing links or connect two contacts with the right type.
Conversation logging – capture message threads with contacts and keep channel context.
Call logging – track phone conversations with quick notes and timestamps.
Group management – curate contact groups and review who belongs in them.
Reminder scheduling – set recurring nudges so you follow up with people on time.
Task management – add follow-ups, update status, or retarget tasks to the right contact.
Note capture – create and manage journal notes from assistant prompts.
Tag system – organize and categorize contacts with custom tags.
Contact resources – stream Monica contact profiles and recent notes as MCP resources.
Task visibility – surface open/completed tasks globally or per contact.
Connectivity probe – quick health check tool for debugging credentials.
Prerequisites
Node.js 18 or newer.
A Monica CRM instance (self-hosted or hosted) with an API token.
Optional: legacy user token if you still rely on
X-Auth-Token/X-User-Tokenauth.
Installation
Configuration
Create a .env file (or set environment variables another way) with at least:
Running the server
Develop:
npm run devType-check:
npm run typecheckBuild:
npm run buildStart (compiled):
npm run start
The dev script launches the MCP server over stdio with live reload for local testing (e.g. using mcp-cli).
Claude Desktop integration
Add the provider to your Claude Desktop ~/.claude-desktop/config.json (or the equivalent per-platform path):
For development, you can swap node dist/index.js with npm run dev --silent to use the TypeScript entry point directly.
Tools exposed
This Monica MCP server provides 21 tools covering the most common CRM operations:
Tool | Purpose |
Core Contact Management | |
| Search Monica CRM contacts by name, nickname, or email. Returns contact IDs and basic info for downstream tools. |
| Retrieve paginated contact lists without a search query. Supports multiple detail tiers and optional filters (gender, tags, communication touch points). |
| Retrieve summaries or manage profile fields, communication details, and addresses with a single
parameter. |
| Simplified wrapper to create/update/delete contact profiles (delegates to
with
). |
| Simplified wrapper to list/get/create/update/delete contact fields like email and phone (delegates to
with
). |
| Simplified wrapper to list/get/create/update/delete contact addresses (delegates to
with
). |
| Manage Monica contact field types (list/get/create/update/delete) so you can add new social or custom field types like "Instagram". |
| Manage tag assignments for a contact (list/append/remove) so you can attach labels like "Close Friend". |
Communication & Interactions | |
| Manage conversations and their messages (list/get/create/update/delete plus message add/update/remove). Channel can be supplied by ID or name. |
| Log calls with contacts (list/get/create/update/delete) to capture quick phone notes. |
| Track meetings/events with contacts. Accepts either
or
. |
| List, inspect, create, update, or delete notes attached to a contact. |
Planning & Follow-ups | |
| Manage Monica tasks and reminders together—choose the item type to list/get/create/update/delete either resource. |
| Manage Monica gifts and debts with a single tool (set
to "gift" or "debt"). |
Media & Files | |
| Manage Monica documents and photos (set
to "document" or "photo"; supports list/get/upload/delete with file path or base64 input). |
Relationships & Organization | |
| List, inspect, create, update, or delete relationships between contacts. Accepts either
or
. |
| List, inspect, create, update, or delete contact groups and review their members. |
| List, inspect, create, update, or delete tags used to categorize contacts. |
Metadata & System | |
| Manage Monica activity types (list/get/create/update/delete) so you can add entries like "Meal" before logging activities. |
| Browse Monica catalogs (genders, countries, contact field types, activity types, relationship types) with optional name filtering. |
| Verify that the configured Monica credentials work. |
Resources exposed
Resource URI | Description |
| JSON payload containing normalized contact profile data. |
| JSON payload with the latest notes for the contact. |
Each resource supports auto-complete on contactId via Monica search so assistants can discover relevant IDs.
Observability & safety
Structured logging via
pino, with token redaction.Requests run with a 15s timeout by default.
Errors from Monica are wrapped as tool outputs (not protocol errors) so assistants can self-correct.
Set
MCP_LOG_FILE=/path/to/monica-mcp.logif you want the server to mirror logs to disk while keeping stdout clean for MCP.
Next steps
Expand tool coverage (activities, reminders, gifts) as needed.
Add caching or rate limiting for heavy workspaces.
Package the server as an executable for easier distribution.
Refer to docs/architecture.md for a deeper design walkthrough and Monica API references pulled from the upstream docs.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Enables interaction with Monica CRM instances to manage contacts, activities, tasks, notes, relationships, and reminders through natural language, wrapping Monica's REST API with 21 assistant-friendly tools.