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
npm install
Configuration
Create a .env file (or set environment variables another way) with at least:
MONICA_API_TOKEN=your-token
# Defaults to https://app.monicahq.com; change for self-hosted instances
MONICA_BASE_URL=https://app.monicahq.com
# one of: bearer (default), apiKey, legacy
MONICA_TOKEN_TYPE=bearer
# Required only when MONICA_TOKEN_TYPE=legacy
MONICA_USER_TOKEN=optional-legacy-user-token
# Optional pino log level (fatal|error|warn|info|debug|trace|silent)
LOG_LEVEL=info
Running the server
- Develop:
npm run dev - Type-check:
npm run typecheck - Build:
npm run build - Start (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):
{
"mcpServers": {
"monica-crm": {
"command": "node",
"args": ["/absolute/path/to/monica-crm-mcp/dist/index.js"],
"env": {
"MONICA_API_TOKEN": "your-token",
"MONICA_BASE_URL": "https://app.monicahq.com"
}
}
}
}
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 | |
monica_search_contacts | Search Monica CRM contacts by name, nickname, or email. Returns contact IDs and basic info for downstream tools. |
monica_list_contacts | Retrieve paginated contact lists without a search query. Supports multiple detail tiers and optional filters (gender, tags, communication touch points). |
monica_manage_contact | Retrieve summaries or manage profile fields, communication details, and addresses with a single section parameter. |
monica_manage_contact_profile | Simplified wrapper to create/update/delete contact profiles (delegates to monica_manage_contact with section="profile"). |
monica_manage_contact_field | Simplified wrapper to list/get/create/update/delete contact fields like email and phone (delegates to monica_manage_contact with section="field"). |
monica_manage_contact_address | Simplified wrapper to list/get/create/update/delete contact addresses (delegates to monica_manage_contact with section="address"). |
monica_manage_contact_field_type | Manage Monica contact field types (list/get/create/update/delete) so you can add new social or custom field types like "Instagram". |
monica_manage_contact_tags | Manage tag assignments for a contact (list/append/remove) so you can attach labels like "Close Friend". |
| Communication & Interactions | |
monica_manage_conversation | Manage conversations and their messages (list/get/create/update/delete plus message add/update/remove). Channel can be supplied by ID or name. |
monica_manage_call | Log calls with contacts (list/get/create/update/delete) to capture quick phone notes. |
monica_manage_activity | Track meetings/events with contacts. Accepts either activityTypeId or activityTypeName. |
monica_manage_note | List, inspect, create, update, or delete notes attached to a contact. |
| Planning & Follow-ups | |
monica_manage_task_reminder | Manage Monica tasks and reminders together—choose the item type to list/get/create/update/delete either resource. |
monica_manage_financial_record | Manage Monica gifts and debts with a single tool (set recordType to "gift" or "debt"). |
| Media & Files | |
monica_manage_media | Manage Monica documents and photos (set mediaType to "document" or "photo"; supports list/get/upload/delete with file path or base64 input). |
| Relationships & Organization | |
monica_manage_relationship | List, inspect, create, update, or delete relationships between contacts. Accepts either relationshipTypeId or relationshipTypeName. |
monica_manage_group | List, inspect, create, update, or delete contact groups and review their members. |
monica_manage_tag | List, inspect, create, update, or delete tags used to categorize contacts. |
| Metadata & System | |
monica_manage_activity_type | Manage Monica activity types (list/get/create/update/delete) so you can add entries like "Meal" before logging activities. |
monica_browse_metadata | Browse Monica catalogs (genders, countries, contact field types, activity types, relationship types) with optional name filtering. |
monica_health_check | Verify that the configured Monica credentials work. |
Resources exposed
| Resource URI | Description |
|---|---|
monica-contact://{contactId} | JSON payload containing normalized contact profile data. |
monica-contact-notes://{contactId} | 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.