Skip to main content
Glama

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.

ci

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

monica_contacts

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.

monica_contact_info

Contact fields (email, phone, social profiles), postal addresses and tags.

monica_relationships

How contacts are related: partner, parent, friend, colleague…

monica_notes

Things to remember about someone.

monica_activities

Things done together, with one or more contacts.

monica_calls

Phone calls.

monica_conversations

Message threads, by channel.

monica_reminders

One-off and repeating reminders, listed by when they next come round.

monica_tasks

To-dos tied to a contact.

monica_gifts_debts

Gift ideas, gifts given and received, and money owed either way.

monica_journal

Journal entries.

monica_reference

Genders, countries, currencies, activity types, relationship types, contact field types and tags; adds custom ones.

monica_media

Documents and photos attached to contacts.

monica_status

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-mcp

compose.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

MONICA_BASE_URL

https://app.monicahq.com

The Monica instance

MONICA_API_TOKEN

required

Its API token

MONICA_API_TOKEN_FILE

Instead: a file holding the token, read again when it changes

MONICA_TOKEN_TYPE

bearer

apiKey sends X-Api-Key; legacy sends X-Auth-Token with MONICA_USER_TOKEN

MCP_TRANSPORT

stdio

http to serve at /mcp

PORT

8080

HTTP only

MCP_BEARER_TOKEN

HTTP: the token clients send

MCP_OAUTH_ISSUER, MCP_OAUTH_CANONICAL_URL, MCP_OAUTH_AUDIENCE, MCP_OAUTH_JWKS_URI

HTTP: optional OAuth 2.1

MONICA_TIMEOUT_MS

15000

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

monica_search_contacts, monica_list_contacts

monica_contacts (search, list)

monica_manage_contact, monica_manage_contact_profile

monica_contacts (get, create, update, delete)

monica_manage_contact_field, monica_manage_contact_address, monica_manage_contact_tags

monica_contact_info (kind: field, address, tag)

monica_manage_relationship

monica_relationships

monica_manage_note, monica_manage_activity, monica_manage_call, monica_manage_conversation

monica_notes, monica_activities, monica_calls, monica_conversations

monica_manage_task_reminder

monica_reminders, monica_tasks

monica_manage_financial_record

monica_gifts_debts

monica_manage_media

monica_media

monica_browse_metadata, monica_manage_activity_type, monica_manage_contact_field_type, monica_manage_tag

monica_reference

monica_health_check

monica_status

monica_manage_group

removed: Monica 4's API has no groups endpoint

resources monica-contact://, monica-contact-notes://

removed: monica_contacts get returns both

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 Monica

The 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 tools

License

MIT

Available Tools

14 tools
monica_activitiesA
Destructive

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_callsA
Destructive

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_infoA
Destructive

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_contactsA
Destructive

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_conversationsA
Destructive

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_debtsA
Destructive

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_journalA
Destructive

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_mediaA
Destructive

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_notesA
Destructive

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_referenceA
Destructive

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_relationshipsA
Destructive

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_remindersA
Destructive

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_statusA
Read-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_tasksA
Destructive

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

    A4.1/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers