Keepsake MCP

1# keepsake-mcp
2 
3MCP server for [Keepsake](https://keepsake.place) — the personal CRM that helps you nurture your relationships.
4 
5Connect your AI assistant (Claude, Cursor, or any MCP-compatible client) to your Keepsake data: contacts, interactions, tasks, notes, daily journal, companies, and tags.
6 
7## Why
8 
9Your AI assistant becomes a personal relationship manager. Ask it to:
10 
11- "Who did I last talk to at Acme Corp?"
12- "Add a note that I ran into Sarah at the conference"
13- "What tasks are overdue?"
14- "Show me everything related to the #house-project tag"
15- "Create a follow-up task for my meeting with John next week"
16 
17## Quick start
18 
19### 1. Get your API key
20 
21Sign up at [keepsake.place](https://keepsake.place), then go to **Account > API Keys** to generate one.
22 
23### 2. Configure your MCP client
24 
25#### Claude Desktop
26 
27Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
28 
29```json
30{
31  "mcpServers": {
32    "keepsake": {
33      "command": "npx",
34      "args": ["-y", "keepsake-mcp"],
35      "env": {
36        "KEEPSAKE_API_KEY": "ksk_YOUR_API_KEY"
37      }
38    }
39  }
40}
41```
42 
43#### Claude Code
44 
45```bash
46claude mcp add keepsake -- npx -y keepsake-mcp
47```
48 
49Then set `KEEPSAKE_API_KEY` in your environment.
50 
51#### Cursor
52 
53Add to `.cursor/mcp.json` in your project:
54 
55```json
56{
57  "mcpServers": {
58    "keepsake": {
59      "command": "npx",
60      "args": ["-y", "keepsake-mcp"],
61      "env": {
62        "KEEPSAKE_API_KEY": "ksk_YOUR_API_KEY"
63      }
64    }
65  }
66}
67```
68 
69## Available tools (42)
70 
71### Contacts
72| Tool | Description |
73|------|-------------|
74| `list_contacts` | List all contacts with pagination and sorting |
75| `get_contact` | Get a contact with recent interactions, tags, and stats |
76| `create_contact` | Create a new contact |
77| `update_contact` | Update contact fields |
78| `delete_contact` | Permanently delete a contact |
79| `search_contacts` | Accent-insensitive search by name, email, company |
80| `get_contact_timeline` | Unified chronological feed of all items for a contact |
81 
82### Companies
83| Tool | Description |
84|------|-------------|
85| `list_companies` | List all companies |
86| `get_company` | Get company with linked contacts and tags |
87| `create_company` | Create a new company |
88| `update_company` | Update company fields |
89| `delete_company` | Soft-delete (or permanent delete) a company |
90| `search_companies` | Accent-insensitive company search |
91 
92### Entries (Interactions)
93| Tool | Description |
94|------|-------------|
95| `list_entries` | List interactions (calls, emails, meetings, etc.) |
96| `create_entry` | Log a new interaction — supports `#tag#` and `[[tag]]` syntax |
97| `update_entry` | Update an interaction |
98| `delete_entry` | Delete an interaction |
99 
100### Tasks
101| Tool | Description |
102|------|-------------|
103| `list_tasks` | List tasks with status/date filters |
104| `create_task` | Create a task — supports `#tag#` and `[[tag]]` syntax |
105| `update_task` | Update task fields |
106| `delete_task` | Delete a task |
107| `complete_task` | Mark as completed (auto-creates next occurrence for recurring tasks) |
108| `uncomplete_task` | Mark as pending again |
109| `snooze_task` | Reschedule to a new date |
110| `get_tasks_today` | Today's tasks: overdue + due today + ASAP |
111| `get_tasks_overdue` | Only overdue tasks |
112 
113### Quick Notes
114| Tool | Description |
115|------|-------------|
116| `list_notes` | List notes (filter by pinned/archived) |
117| `create_note` | Create a note — supports `#tag#` and `[[tag]]` syntax |
118| `update_note` | Update note content |
119| `delete_note` | Soft-delete (or permanent) |
120| `pin_note` | Pin to top |
121| `archive_note` | Archive a note |
122| `restore_note` | Restore a deleted/archived note |
123 
124### Daily Journal
125| Tool | Description |
126|------|-------------|
127| `list_days` | List journal entries by date range |
128| `get_day` | Get a specific day's journal |
129| `update_day` | Create or update a day's journal (upsert) |
130 
131### Tags
132| Tool | Description |
133|------|-------------|
134| `list_tags` | List all tags |
135| `get_tag_items` | Get everything linked to a tag |
136| `link_tag` | Link any entity to a tag |
137| `unlink_tag` | Remove a tag link |
138 
139### Utilities
140| Tool | Description |
141|------|-------------|
142| `search` | Global search across all data types |
143| `get_changelog` | Items modified since a timestamp (for sync) |
144| `get_agent_instructions` | Best practices for AI agents |
145 
146## Tool annotations
147 
148All tools include MCP safety annotations:
149 
150- **Read-only tools** (`list_*`, `get_*`, `search_*`): marked `readOnlyHint: true`
151- **Create tools**: marked `destructiveHint: false`
152- **Update tools**: marked `destructiveHint: false, idempotentHint: true`
153- **Delete tools**: marked `destructiveHint: true, idempotentHint: true`
154 
155## Environment variables
156 
157| Variable | Required | Description |
158|----------|----------|-------------|
159| `KEEPSAKE_API_KEY` | Yes | Your API key (starts with `ksk_`) |
160| `KEEPSAKE_API_URL` | No | Custom API URL (default: `https://app.keepsake.place/api/v1`) |
161 
162## Rate limits
163 
16460 requests per minute per API key. Rate limit headers are included in responses.
165 
166## API documentation
167 
168Full REST API docs: [keepsake.place/api](https://keepsake.place/en/api)
169 
170## Privacy
171 
172Keepsake MCP server only communicates with the Keepsake API (`app.keepsake.place`). It does not send data to any third-party service. Your data stays between your MCP client and your Keepsake account.
173 
174All API calls are authenticated with your personal API key and scoped to your account via Row Level Security. No other user's data is accessible.
175 
176See our privacy policy at [keepsake.place/privacy](https://keepsake.place/en/privacy).
177 
178## License
179 
180MIT
181