Monica CRM MCP Server

# 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 fields** – manage phone numbers, emails, social media handles, and custom contact information. - **Activity tracking** – capture meetings/outings and review recent shared history. - **Activity catalog** – curate activity types and categories the assistant can use. - **Address management** – keep contact address book entries in sync from the assistant. - **Relationship management** – inspect existing links or connect two contacts with the right type. - **Relationship types** – manage the catalog of relationship types (family, friends, colleagues, etc.). - **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. - **Metadata lookups** – access country and gender catalogs for proper data validation. - **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-Token` auth. ## Installation ```bash 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): ```json { "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 all major 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. Use the returned ID with other tools to get details or make updates. | | `monica_get_contact_summary` | Retrieve full profile details for a specific contact ID (includes custom fields when `includeContactFields: true`). Use this after searching to see complete contact information before making updates. | | `monica_manage_contact` | Create, update, or delete contacts in Monica CRM. Use this for basic profile info (name, gender, description, birthdate). For phone numbers and emails, use contact field management instead. | | **Contact Fields & Communication** | | | `monica_manage_contact_field` | PREFERRED FOR PHONES/EMAILS: Add, update, or remove phone numbers, emails, and other contact information. Also handles custom fields like social media handles. | | `monica_manage_contact_field_type` | ADVANCED: Manage the types/categories of contact fields (like "Mobile Phone", "Work Email"). Most users should use monica_manage_contact_field directly instead. | | **Addresses & Location** | | | `monica_manage_address` | Manage physical addresses for contacts. Use this to add home, work, or other addresses to contact profiles. | | `monica_lookup_country` | Retrieve the supported country catalog (name, ISO code, Monica ID). Use this before creating or updating addresses so you can map human-friendly names to the correct country identifier. | | **Activities & Events** | | | `monica_manage_activity` | Manage activities (meetings, calls, events) in Monica CRM. Use this to track interactions and shared experiences with contacts. | | `monica_manage_activity_type` | List, inspect, create, update, or delete Monica activity types. | | `monica_manage_activity_type_category` | List, inspect, create, update, or delete activity type categories. | | **Notes & Documentation** | | | `monica_create_note` | Attach a note to a Monica contact. | | `monica_manage_note` | List, inspect, create, update, or delete notes attached to a contact. Use this to capture or revise journal snippets. | | **Tasks & Follow-ups** | | | `monica_manage_task` | List, inspect, create, update, or delete tasks. Use this to add follow-ups, mark them complete, or target them to another contact. | | `monica_list_tasks` | List tasks across Monica CRM or for a specific contact. | | `monica_manage_reminder` | List, inspect, create, update, or delete reminders to stay in touch with contacts. | | **Relationships & Social Connections** | | | `monica_manage_relationship` | List, inspect, create, update, or delete relationships between contacts. Use this to confirm existing connections or link two contacts once you know the correct relationshipTypeId. | | `monica_manage_relationship_type` | List, inspect, create, update, or delete relationship types. Use this to manage the catalog of relationship types (like "Father", "Friend", "Colleague") that can be used when creating relationships between contacts. | | `monica_manage_relationship_type_group` | List and inspect relationship type groups. These are system-defined categories (like "love", "family", "friend", "work") used to organize relationship types. Note: This endpoint is read-only. | | **Tags & Organization** | | | `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. Tags allow you to group and categorize contacts. | | **System & Metadata** | | | `monica_lookup_gender` | Fetch the gender catalog so you can supply the correct genderId when creating or updating contacts. Monica requires a genderId for every contact profile. | | `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. ## Next steps 1. Expand tool coverage (activities, reminders, gifts) as needed. 2. Add caching or rate limiting for heavy workspaces. 3. 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.