ESEN
View on GitHub

A personal CRM to look after your relationships

Self-hosted. People, important dates and reminders, with encrypted notes and attachments.

View on GitHubInstallDocker Compose. Your data stays on your server.
Simple CRM people list in the dark theme, with cards showing tags, contact status and cadence filters.

The app, as it is

Real screenshots of the application with demo data.

Pick a frame or use keys 1 to 5.

Simple CRM home screen in the dark theme: monthly calendar, pending reminders, favorite people, upcoming dates and suggestions to reach out.
Calendar, pending items, upcoming dates and who to write to next.
Simple CRM people list in the dark theme, with cards showing tags, contact status and cadence filters.
Cards with tags, cadence filters and contact status.
Simple CRM reminders board in the dark theme, with To do, In progress and Done columns.
Reminders in columns: to do, in progress and done.
Simple CRM Settings, Integrations tab: MCP access switch, server URL, token and snippets to set up a client.
Settings > Integrations: URL, token and the block ready for your client.
Simple CRM home screen in the light theme, with the same calendar, pending items, favorites and upcoming dates.
Light or dark theme, with the accent color you choose.

Install

You need Docker with Compose v2 and Python 3 (only to generate the secrets).

Quick start

  1. Clone and generate secrets

    The script creates .env.docker with the Django secret, the encryption key and the Postgres password.

  2. Start the stack

    Docker Compose builds and starts the database, the backend, the frontend and the proxy.

  3. Open the app

    Go to 127.0.0.1:8080 and create your account at /register/. Registration closes after the first user.

bash
git clone https://github.com/chaska-dev/SimpleCRM.git
cd SimpleCRM
python scripts/generate-secrets.py
docker compose --env-file .env.docker up -d --build

Then open http://127.0.0.1:8080 and create the first account at /register/.

Back up FIELD_ENCRYPTION_KEYS outside the server: if you lose it, encrypted notes and attachments cannot be recovered. On Linux or macOS the script may be python3.

What is included

  • People and contacts

    One record per person with several channels, tags, favorites, contact cadence and an interaction log.

  • Birthdays and dates

    Yearly dates with calculated age and a view of the upcoming ones.

  • Reminders and board

    Statuses (to do, in progress, done), recurrence and a board view next to the list.

  • Organizations

    Universities, companies and other organizations, with logos and each person's memberships.

  • Encrypted notes and attachments

    Fernet encryption at rest. The key lives in your .env.docker, not in the database.

  • Import and export

    vCard (.vcf) and Google Contacts CSV, with duplicate detection.

  • AI agents via MCP

    Claude Code, Claude Desktop, Cursor or VS Code read and create data with a revocable token.

  • English and Spanish, themes and accent

    English and Spanish interface, light and dark themes, and the accent color you prefer.

Connect an AI agent

The MCP server is optional and off by default. You turn it on in the app and can revoke access at any time.

  1. Turn it on

    In Settings > Integrations, switch on “Allow AI agent access (MCP)”.

  2. Copy URL and token

    Under Connection, copy the server URL and the token. If there is none, press “Generate token”; “Test connection” checks it.

  3. Paste the block

    Under Set up your client, pick Claude Code, Claude Desktop, Cursor or VS Code and paste the block, already filled with your URL and token.

What each client block looks like

Claude Code
claude mcp add --transport http simple-crm http://127.0.0.1:8080/mcp/ --header "Authorization: Bearer <TOKEN>"
Claude Desktop
{
  "mcpServers": {
    "simple-crm": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8080/mcp/", "--header", "Authorization:Bearer <TOKEN>"]
    }
  }
}
Cursor
{
  "mcpServers": {
    "simple-crm": {
      "url": "http://127.0.0.1:8080/mcp/",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}
VS Code
{
  "servers": {
    "simple-crm": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp/",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

In the app they come with your real URL and token; here <TOKEN> is a placeholder. Claude Desktop needs Node.js.

A localhost URL only works on the same computer. To connect from another device, open the app through your network IP and publish the port (see the configuration guide in the repository).

Import and export contacts

In Settings > Import and export. Nothing is written until you review the preview.

Import

Upload a .vcf exported from Android, iPhone (iCloud) or Google Contacts, or a Google Contacts CSV. You see the duplicates and choose to skip, complete or create them anyway.

Export

Export to vCard or Google CSV, all contacts or one tag. Notes are only included if you ask for them, and then they leave unencrypted.