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-Token auth.

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: