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

Environment Variable	Required	Default	Description
MONICA_API_TOKEN	Yes	—	Bearer token for Monica API
MONICA_BASE_URL	No	https://app.monicahq.com	Your Monica instance URL
MONICA_READ_ONLY	No	false	Block all create/update/delete operations
MONICA_DISABLE_DELETE	No	false	Block only delete operations
MONICA_EXCLUDE_TOOLS	No	—	Comma-separated tool names to exclude

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

Tool	Actions	Description
monica_contact	list, get, create, update, delete, search, set_tags, update_career, list_activities, list_calls, list_addresses, list_notes, list_tasks, list_reminders, list_gifts, list_debts, list_relationships, list_conversations, list_photos, list_documents, list_fields, list_audit_logs, assign_tag, remove_tag	Full contact management with 15+ contact-scoped sub-queries
monica_address	list, get, create, update, delete	Address CRUD
monica_contact_field	list, get, create, update, delete	Contact field CRUD (email, phone, etc.)
monica_contact_field_type	list, get, create, update, delete	Contact field type CRUD
monica_company	list, get, create, update, delete	Company CRUD
monica_occupation	list, get, create, update, delete	Occupation CRUD
monica_group	list, get, create, update, delete	Contact group CRUD

Communication

Tool	Actions	Description
monica_activity	list, get, create, update, delete	Activity CRUD
monica_activity_type	list, get, create, update, delete	Activity type CRUD
monica_activity_type_category	list, get	Activity type categories (read-only)
monica_call	list, get, create, update, delete	Call log CRUD
monica_conversation	list, get, create, update, delete, list_messages, add_message, update_message, delete_message	Conversation + message threading

Productivity

Tool	Actions	Description
monica_note	list, get, create, update, delete	Note CRUD
monica_task	list, get, create, update, delete	Task CRUD
monica_reminder	list, get, create, update, delete	Reminder CRUD
monica_tag	list, get, create, update, delete	Tag CRUD
monica_journal_entry	list, get, create, update, delete	Journal entry CRUD

Professional & Financial

Tool	Actions	Description
monica_relationship	list, get, create, update, delete	Relationship CRUD
monica_relationship_type	list, get	Relationship types (read-only per API)
monica_relationship_type_group	list, get	Relationship type groups (read-only per API)
monica_gift	list, get, create, update, delete, associate_photo	Gift CRUD + photo association
monica_debt	list, get, create, update, delete	Debt CRUD

Reference Data (read-only)

Tool	Actions	Description
monica_country	list, get	Countries
monica_currency	list, get	Currencies
monica_gender	list, get	Genders
monica_audit_log	list	Audit logs
monica_user	get	Authenticated user info
monica_photo	list, get	Photos (upload not supported by Monica API)
monica_document	list, get	Documents (upload not supported by Monica API)

API Limitations

Feature	Status	Reason
Photo upload	Not supported	Monica API returns 405
Document upload	Not supported	Monica API returns 405

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