monica-mcp

A full-coverage Model Context Protocol server for Monica CRM. 29 tools covering all 30 API endpoints — search contacts, log activities, manage notes/tasks/reminders, track relationships, and more.

Designed for AI assistants like Claude Desktop, Hermes, Cline, and any MCP-compatible client.

Note: This project is 100% AI-generated. The code, tests, CI/CD, and documentation were all written by an AI agent (Hermes). No human wrote any of the code.

Tested against a live Monica v4.1.2 instance on the author's homelab. All 29 tools validated with create → read → update → delete lifecycle tests. Test data was cleaned up after verification.

Design Philosophy

Action-based tools (not one tool per CRUD op)

Most MCP servers expose 5 separate tools per entity (list, get, create, update, delete). With 30 entities that's 150 tools — flooding the LLM's context window with ~50K+ tokens just for tool definitions. Research shows tool selection accuracy degrades quickly past 15-20 tools.

This server uses one tool per entity with an action parameter:

monica_contact(action: "list" | "get" | "create" | "update" | "delete", ...)

Result: 29 tools instead of 150+, ~10-15K tokens for definitions, and better tool selection accuracy.

Safety by design

• Delete is an action, not a tool — the AI must explicitly pass action: "delete" rather than calling a tool named "delete"

• Read-only mode — set MONICA_READ_ONLY=true to block all write operations

• Delete protection — set MONICA_DISABLE_DELETE=true to block only deletes

• Tool exclusion — set MONICA_EXCLUDE_TOOLS=monica_contact,monica_tag to remove specific tools

• Read-only entities — countries, currencies, genders have no create/update/delete actions

• Delete warnings — every tool description includes "⚠️ delete is irreversible"

Quick Start

npx (recommended)

{
  "mcpServers": {
    "monica": {
      "command": "npx",
      "args": ["-y", "monica-mcp"],
      "env": {
        "MONICA_BASE_URL": "https://your-monica-instance.com",
        "MONICA_API_TOKEN": "your-bearer-token"
      }
    }
  }
}

Read-only mode (recommended for exploration)

{
  "mcpServers": {
    "monica": {
      "command": "npx",
      "args": ["-y", "monica-mcp"],
      "env": {
        "MONICA_BASE_URL": "https://your-monica-instance.com",
        "MONICA_API_TOKEN": "your-bearer-token",
        "MONICA_READ_ONLY": "true"
      }
    }
  }
}

Local development

git clone https://github.com/philipp-mlr/monica-mcp.git
cd monica-mcp
npm install
npm run build
MONICA_BASE_URL=https://your-monica-instance.com MONICA_API_TOKEN=your-token node dist/index.js

Configuration

Getting an API token

In Monica, go to Settings → API → Create New Token. Copy the generated Bearer token.

Tool Reference

All 29 tools use an action parameter. Available actions vary per entity — see each tool's description for details.

Contact Management

Communication

Productivity

Professional & Financial

Reference Data (read-only)

API Limitations

Tech Stack

• Node.js 18+ — runtime

• TypeScript — type safety

• @modelcontextprotocol/sdk — MCP protocol implementation

• Zod — input validation

• Vitest — testing

Development

npm run dev              # Start with hot reload (tsx watch)
npm run typecheck        # Type-check without emitting
npm test                 # Run tests (26 tests)
npm test -- --coverage   # Run tests with coverage

Roadmap

• Automated integration tests — spin up a fresh Monica Docker container in CI, run tools against it, tear it down. This would catch API regressions before they affect users.

• Rate limiting — respect Monica's 60 req/min limit with client-side throttling

• Photo/document upload — if Monica's API ever supports these, add the tools back

• npm release cadence — publish new versions automatically when the version watchdog detects a Monica release that passes integration tests

Publishing to npm

This package is published to npmjs.com for npx usage.

First-time setup

# 1. Create an npm account at https://www.npmjs.com/signup
# 2. Login on the CLI
npm login

# 3. Verify you're logged in
npm whoami

Publishing a new version

# 1. Bump the version in package.json
npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
npm version minor   # 0.1.0 → 0.2.0 (new features, backwards compatible)
npm version major   # 0.1.0 → 1.0.0 (breaking changes)

# 2. Build and publish
npm run build
npm publish

# Or dry-run first to see what gets published:
npm publish --dry-run

CI/CD auto-publish

The included GitHub Actions workflow (.github/workflows/release.yml) auto-publishes to npm when a tag v*.*.* is pushed. To use this:

1. Create an npm Automation access token at https://www.npmjs.com/settings/~/tokens (type must be Automation, not "Publish" — Automation tokens bypass 2FA)

2. Add it as a GitHub secret: NPM_TOKEN

3. Tag and push:

   npm version patch
   git push origin main --tags

License

MIT