Monica CRM

You are about to run an MCP server that lets assistants read from and write to Monica CRM. It wraps Monica’s REST API with practical tools so you can search contacts, manage timelines, capture notes, and track tasks directly from chat, without switching apps.

How to use

Connect your MCP client to the Monica CRM MCP Server to enable command-based access to Monica data. You can search contacts, view contact summaries, log notes and calls, manage tasks and reminders, and navigate metadata catalogs from within your chat, using the exposed tools.

In practical terms, you will start by ensuring your server is running, then configure your MCP client to point to the local stdio or remote HTTP endpoint as shown in the setup steps. Once connected, you can perform common CRM actions through the available tools, such as searching for a contact, listing groups, logging a call, or creating a task, all from the chat interface.

How to install

Prerequisites you need before installation:

• Node.js 18 or newer
• A Monica CRM instance with an API token
• Optional: legacy user token if you use legacy X-Auth-Token or X-User-Token auth

Install the MCP server dependencies in your project root:

npm install

Create a configuration file or set environment variables with the required Monica credentials. At minimum include your Monica API token and the base URL of your Monica instance.

MONICA_API_TOKEN=your-token
MONICA_BASE_URL=https://app.monicahq.com
MONICA_TOKEN_TYPE=bearer
# Optional for legacy authentication
MONICA_USER_TOKEN=optional-legacy-user-token
LOG_LEVEL=info

Run and test the server

For development and testing, you can run the MCP server in development mode to enable live reload and quick iteration.

npm run dev

If you prefer to compile and run the production build, use the standard build and start sequence.

npm run build
npm run start

Claude Desktop integration

To connect Claude Desktop to the Monica MCP Server, add a new MCP provider with a stdio command that launches the server’s entry point and passes the required environment variables.

{
  "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"
      }
    }
  }
}

Available tools

monica_search_contacts

Search Monica CRM contacts by name, nickname, or email and return IDs and basic details for downstream tools.

monica_list_contacts

Retrieve paginated contact lists with optional detail tiers and filters (gender, tags, touch points).

monica_manage_contact

Retrieve contact summaries or update profile fields, communication details, and addresses using a single section parameter.

monica_manage_contact_profile

Wrapper to create/update/delete contact profiles via monica_manage_contact with section=profile.

monica_manage_contact_field

List/get/create/update/delete contact fields like email and phone via monica_manage_contact with section=field.

monica_manage_contact_address

List/get/create/update/delete contact addresses via monica_manage_contact with section=address.

monica_manage_contact_field_type

Manage contact field types (list/get/create/update/delete) to add new field types such as social handles.

monica_manage_contact_tags

Manage tag assignments for a contact (list/append/remove).

monica_manage_conversation

Manage conversations and messages (list/get/create/update/delete). 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 activityTypeId or activityTypeName.

monica_manage_note

List, inspect, create, update, or delete notes attached to a contact.

monica_manage_task_reminder

Manage tasks and reminders together—list/get/create/update/delete. Includes per-item scope.

monica_manage_financial_record

Manage gifts and debts with a single tool (set recordType to gift or debt).

monica_manage_media

Manage documents and photos (set mediaType to document or photo; supports list/get/upload/delete).

monica_manage_relationship

List, inspect, create, update, or delete relationships between contacts by type/name.

monica_manage_group

List, inspect, create, update, or delete contact groups and view members.

monica_manage_tag

List, inspect, create, update, or delete tags used to categorize contacts.

monica_manage_activity_type

Manage Monica activity types (list/get/create/update/delete) to add entries like Meal.

monica_browse_metadata

Browse Monica catalogs (genders, countries, field types, activity types, relationship types) with optional name filtering.

monica_health_check

Verify credentials and connectivity to Monica CRM.