Monica CRM MCP Server
An MCP server that connects MCP clients to a Monica 4 personal CRM, letting you find and manage contacts plus everything attached to them.
Contacts — search by name/nickname/email, or paginate a list with filters (gender, tags, has email/phone) at minimal/basic/expanded/full detail; create, update, delete and read full profiles (nickname, gender, birthdate/age or unknown, deceased status, description).
Contact info — email, phone and social handles (fields and field types), postal addresses with automatic country lookup, and tag assignments (list, append, remove).
Relationships — connect contacts as partner, parent, friend, colleague, etc., via relationship types.
Interactions — activities (meetings/events with one or more contacts), conversations and their messages by channel, and logged phone calls.
Notes — create, read, update and delete notes on a contact.
Tasks & reminders — to-dos and stay-in-touch nudges, one-off or repeating (day/week/month/year), filtered by status.
Gifts & debts — presents given or received, gift ideas, and money owed either way, with amounts, currency and settled status.
Media — list, inspect, upload (base64) and delete documents and photos.
Groups — organize contacts into named collections.
Reference data — browse genders, countries, currencies, occupations, contact field types, activity types and relationship types; add or edit custom ones.
Status — check that the Monica connection and credentials work.
Behaviour worth relying on — contacts and types accepted by name or id, inputs validated before reaching Monica, updates merge rather than overwrite, deletes need
confirm: true, compact results, and rate-limit-aware retries.
Note: the exposed schema is the 1.x tool set (e.g. monica_manage_group, monica_manage_contact_profile), whereas the README documents the 2.0 rewrite with 14 consolidated tools (monica_contacts, monica_journal, etc.).
Provides comprehensive contact relationship management through Monica CRM's API, including contact search and management, activity tracking, task and reminder scheduling, note capture, relationship mapping, address management, and custom field handling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Monica CRM MCP Server find John Smith's contact details and show me his recent notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Monica MCP
An MCP server for Monica, the personal CRM: contacts, notes, activities, reminders and more, for any MCP client.
It targets Monica 4 (the classic version, 4.1.2 being its latest release), through its REST API. Monica 5 is a separate rewrite, still in beta, with a different API.
Self-hosting Monica as well? Monica Server Stack runs Monica 4 and this server together in one Docker Compose project, with the account and API token set up automatically.
What it does
Tool | For |
| Search, list, read, create, update and delete contacts, including job, company and how they met. A contact's profile comes with its details, recent notes, activities and reminders. |
| Contact fields (email, phone, social profiles), postal addresses and tags. |
| How contacts are related: partner, parent, friend, colleague… |
| Things to remember about someone. |
| Things done together, with one or more contacts. |
| Phone calls. |
| Message threads, by channel. |
| One-off and repeating reminders, listed by when they next come round. |
| To-dos tied to a contact. |
| Gift ideas, gifts given and received, and money owed either way. |
| Journal entries. |
| Genders, countries, currencies, activity types, relationship types, contact field types and tags; adds custom ones. |
| Documents and photos attached to contacts. |
| Checks the connection. |
How it's built to behave:
People by name. Every tool takes a contact's name or id. A name that matches several people is refused with the candidates and their ids; types, genders and countries are matched by name too.
Few tools, one action each call. Fourteen tools, each with an
action, rather than dozens. Inputs are validated before anything reaches Monica, and invalid ones are rejected with what's allowed (date: use YYYY-MM-DD,no gender "Robot". Choose one of: Man, Woman, Rather not say).Safe edits. Updates change only what's given and keep the rest. Monica's own update API clears anything left out, so the server reads the record first. Deleting anything needs
confirm: true.Compact answers. Results are trimmed to what's useful: names instead of nested objects, plain dates, no API noise.
Gentle with Monica. Monica allows 60 API requests a minute by default. The server remembers names it has already resolved, and waits and retries when Monica asks it to slow down.
Tested against a real Monica. CI sets up Monica 4.1.2 from scratch and runs every tool against it (
scripts/e2e.mjs).
Related MCP server: Bitrix24 MCP Server
Install
Requires Node.js 20.12 or newer, a Monica 4 instance (self-hosted, or monicahq.com) and an API token from it (Settings → API → Create a new token).
To set up Monica and this server together, monica-server-stack does it in one Docker Compose project: the account, the API token (renewed before it expires), the scheduler for reminders, and optional HTTPS.
Desktop clients (stdio)
Most MCP clients take a configuration like this:
{
"mcpServers": {
"monica": {
"command": "npx",
"args": ["-y", "github:Jacob-Stokes/monica-mcp"],
"env": {
"MONICA_BASE_URL": "https://monica.example.com",
"MONICA_API_TOKEN": "the-token"
}
}
}
}Or from a clone: git clone https://github.com/Jacob-Stokes/monica-mcp && cd monica-mcp && npm install, then "command": "node", "args": ["/path/to/monica-mcp/dist/index.js"].
As a service (HTTP)
With MCP_TRANSPORT=http, the server speaks Streamable HTTP at /mcp and requires MCP_BEARER_TOKEN (or OAuth) on every request. The Docker image runs this way:
docker build -t monica-mcp https://github.com/Jacob-Stokes/monica-mcp.git
docker run -d -p 127.0.0.1:8080:8080 \
-e MONICA_BASE_URL=https://monica.example.com -e MONICA_API_TOKEN=... -e MCP_BEARER_TOKEN=... \
monica-mcpcompose.example.yml runs it next to a Monica container. For clients that log in with OAuth 2.1, set MCP_OAUTH_ISSUER, MCP_OAUTH_CANONICAL_URL and, if the issuer puts the client id in aud, MCP_OAUTH_AUDIENCE. /health answers without authentication.
Configuration
Variable | Default | |
|
| The Monica instance |
| required | Its API token |
| Instead: a file holding the token, read again when it changes | |
|
|
|
|
|
|
|
| HTTP only |
| HTTP: the token clients send | |
| HTTP: optional OAuth 2.1 | |
|
| Per request to Monica |
A .env file in the working directory is read when the variables aren't already set. Logs go to stderr.
A self-hosted Monica's API limit can be raised with RATE_LIMIT_PER_MINUTE_API in Monica's own environment; 60 a minute is tight for an assistant looking around.
Upgrading from 1.x
2.0 is a rewrite. The Monica settings are unchanged, and dist/index.js is still the entry point, so existing client configurations keep working, but the tools are new:
1.x | 2.0 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| removed: Monica 4's API has no groups endpoint |
resources | removed: |
New: monica_journal, the HTTP transport, OAuth, and a Docker image. Details in CHANGELOG.md.
Development
npm install
npm test # build, then unit tests and an HTTP transport test (no Monica needed)
MONICA_BASE_URL=... MONICA_API_TOKEN=... npm run e2e # every tool against a real MonicaThe end-to-end test works on contacts it creates itself and deletes them at the end; point it at a test instance all the same.
src/
index.ts start-up: stdio or HTTP
config.ts environment variables
monica.ts Monica's API: auth, pagination, rate-limit retries, errors
resolve.ts names to ids (contacts, types, countries…)
format.ts compact results
server.ts tool registry, validation, error messages
http.ts Streamable HTTP, bearer and OAuth
schema.ts zod to flat JSON Schema
tools/ the fourteen toolsLicense
MIT
Available Tools
14 toolsmonica_activitiesADestructive
Things done together with contacts (a coffee, a trip, a dinner). • list — a contact's activities, or the most recent across everyone. • get — one activity. • create — log an activity with one or more contacts, a summary and a date (today by default), optionally typed (e.g. 'ate at a restaurant', 'went to a bar'; monica_reference kind=activity_types). • update — change any of it; contacts, if given, replace the list. • delete — remove an activity (confirm: true).
Inputs: action (required), id, date, type, +6 more.
monica_callsADestructive
Phone calls with contacts. • list — a contact's calls, or the most recent across everyone. • create — log a call (date: today by default) with what was said. • update / delete — by id (delete needs confirm: true).
Inputs: action (required), id, date, limit, +3 more.
monica_contact_infoADestructive
A contact's details: contact fields (email, phone, social profiles…), postal addresses, and tags. Choose kind, then: • list — the contact's fields, addresses or tags. • add — a field (type by name, e.g. Email, Phone, Instagram, plus value), an address, or tags (by name; new tags are created). • update — a field or address by its id. • remove — a field or address by id, or tags from the contact by name (confirm: true for fields and addresses). Field types: monica_reference kind=contact_field_types; new types can be added there.
Inputs: kind (required), action (required), id, city, +10 more.
monica_contactsADestructive
People in Monica, the personal CRM. Actions: • search — find contacts by name, nickname, email or other text. Start here when a person is mentioned. • list — browse all contacts, a page at a time. • get — one contact's profile (birthdate, job, how you met, addresses, relationships, tags) plus their contact details, recent notes, activities and reminders; choose more with include. • create — add a contact. Only first_name is required. • update — change any profile field; fields left out are kept, null clears one. • delete — remove a contact and everything attached to it (confirm: true). Everywhere a contact is needed, a name works as well as an id; if a name matches several people, the error lists them with ids.
Inputs: action (required), job, page, sort, +18 more.
monica_conversationsADestructive
Message threads with contacts (texts, emails, chats), kept as conversations of messages. • list — a contact's conversations, or the most recent across everyone. • get — one conversation with its messages. • create — record a conversation on a channel (a contact field type such as Email, Phone, Whatsapp, Telegram) with its messages. • add_message — append a message to a conversation. • delete — remove a conversation (confirm: true).
Inputs: action (required), id, date, from, +6 more.
monica_gifts_debtsADestructive
Gifts (ideas, given, received) and money owed between you and contacts. Choose kind, then: • list — a contact's, or everyone's. • create — gift: name, status (idea, offered, received), optional value, url, comment, date. debt: amount, direction (i_owe or they_owe), reason. • update — by id; a debt can be marked settled. • delete — by id (confirm: true).
Inputs: kind (required), action (required), id, url, +12 more.
monica_journalADestructive
The journal: dated entries about your own days, not tied to a contact. • list — recent entries. • get — one entry. • create — write an entry (date: today by default). • update — change it. • delete — remove it (confirm: true).
Inputs: action (required), id, date, post, +3 more.
monica_mediaADestructive
Documents and photos attached to contacts. Choose kind, then: • list — a contact's, or everyone's. • upload — a file for a contact, from base64 content plus a filename (or, when this server runs on the same machine over stdio, a local path). • delete — by id (confirm: true).
Inputs: kind (required), action (required), id, path, +5 more.
monica_notesADestructive
Notes about contacts: things to remember about someone. • list — a contact's notes, or the most recent notes across everyone. • get — one note in full. • create / update — write a note about a contact; favorite pins it. • delete — remove a note (confirm: true).
Inputs: action (required), id, body, limit, +3 more.
monica_referenceADestructive
Monica's reference lists, which other tools match names against: genders, countries, currencies, activity_types, relationship_types, contact_field_types, tags. • list — a list, optionally filtered by text. • create / rename / delete — your own activity types (e.g. 'climbing'), contact field types (e.g. Instagram, with an optional protocol such as https://instagram.com/), and tags. Deleting needs confirm: true.
Inputs: kind (required), action (required), id, name, +4 more.
monica_relationshipsADestructive
How contacts are related. A relationship reads 'contact is of other', e.g. contact=Alice, type=parent, other=Bob means Alice is Bob's parent; Monica records the reverse (Bob is Alice's child) itself. • list — a contact's relationships. • add — relate two contacts. • update — change a relationship's type. • remove — delete a relationship (confirm: true). Types include partner, spouse, date, ex, parent, child, sibling, grandparent, uncle, cousin, friend, bestfriend, colleague, boss, mentor (monica_reference kind=relationship_types).
Inputs: action (required), id, type, other, +2 more.
monica_remindersADestructive
Reminders about contacts (call Mum on Sunday, a birthday card every year). Monica emails them when due. • list — upcoming reminders, soonest first: a contact's, or everyone's within the next days. • create — a reminder on a date, once or repeating (daily, weekly, monthly, yearly, every N). • update / delete — by id (delete needs confirm: true). Birthday reminders are created by Monica itself when a birthdate is set.
Inputs: action (required), id, date, days, +6 more.
monica_statusARead-only
Check the connection to Monica: the signed-in user, the instance and how many contacts it holds. Useful when other tools fail.
Inputs: no named parameters.
monica_tasksADestructive
To-dos tied to a contact (return their book, send the photos). • list — open tasks (or done ones with done: true), a contact's or everyone's. • create — a task for a contact. • update — change it, or mark it done / not done. • delete — remove it (confirm: true).
Inputs: action (required), id, done, limit, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool maps to a distinct CRM resource (contacts, notes, activities, calls, conversations, reminders, tasks, gifts/debts, journal, media, reference, status). The only apparent overlap—tags/contact field types across monica_contact_info and monica_reference—is clearly bounded: one attaches to a contact, the other manages global reference lists. No two tools appear to do the same thing.
All tool names use snake_case with a consistent monica_ prefix. Although the pattern is resource-noun rather than verb_noun, the convention is uniform and predictable across the set; minor singular/plural variation is not confusing.
14 tools is well-scoped for a personal CRM; each resource area earns its own tool without obvious redundancy. It sits comfortably within the ideal 3–15 range.
Core CRM lifecycle is broadly covered: contacts, notes, activities, calls, conversations, reminders, tasks, gifts/debts, journal, relationships, and media all support list/get/create/update/delete where appropriate. Minor gaps exist (e.g., no get for calls/reminders/tasks, no update for conversations/media), but they are not dead ends for typical agent workflows.
Maintenance
Related MCP Connectors
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
Personal CRM operated by AI agents. Read relationship context before acting, write back after.
Connect AI to your Attio CRM. Manage contacts, companies, deals, and sales pipelines. Create tasks…
Carbon Voice MCP serves as a bridge that connects AI assistants like ChatGPT, Claude, and Cursor to a user's Carbon Voice account, turning voice messages and conversations into a private, on-demand knowledge base. It provides 28 specialized tools for comprehensive voice messaging management, including creating and sending messages, accessing conversation history with instant transcription, running AI actions (summarization, TLDR generation, meeting notes), and managing workspace collaboration through folders, contacts, and team communications.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to manage Folk CRM data, including contacts, companies, notes, and reminders. It supports searching for entities, logging interactions, and setting follow-up tasks through the Folk REST API.6MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with Bitrix24 CRM for managing contacts, deals, tasks, and leads via a comprehensive set of tools. It supports advanced features like sales team monitoring, performance analytics, and automated CRM searching.-
- AlicenseBqualityDmaintenanceEnables AI assistants to manage ActiveCampaign CRM, marketing automation, and contact data via 33 tools including contacts, deals, tags, automations, pipelines, custom fields, campaigns, accounts, and webhooks.6521 PyPI1MIT
- FlicenseCqualityDmaintenanceEnables Claude to interact with GoHighLevel CRM for contact management, messaging, calendar, and sales opportunities via 14 tools.20-