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

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

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

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:

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