# monica-mcp
## 基本信息
- Slug: `jacob-stokes-monica-mcp`
- Source: modelscope
- Publisher: @Jacob-Stokes/monica-mcp
- Categories: customer-data-platforms / content-management-systems / app-automation
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@Jacob-Stokes/monica-mcp
## 简介
暂无描述。
## 安装提示

```bash
npm install
```

## 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 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
```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 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 togetherchoose the item type to list/get/create/update/delete either resource. |
| `monica_manage_financial_record` | Manage Monica gifts and debts …