Curatively
by Abaii
README.md
# curatively-mcp
Your Curatively vault, reachable from Claude Code, Codex, Cursor or any MCP client — as you.
The vault is private. This server signs in as you — approved from the app or the web, or with an email code — so your agent sees exactly what you see: every save, including the ones that are not on your page. Nothing here can publish or delete. It can search, read (pixels included), list and filter, save a photo, link or note, and edit the note you wrote on a save.
Free accounts get all of it. That is a rule, not a launch offer.
## Sign in once
```sh
npx -y curatively-mcp login
```
It prints a code like `K7QM-3XRD` and a link. Approve it on a device where you're already signed in: scan or open the link on a signed-in browser (`curatively.io/pair`), or in the app go to Account → Sign-in methods → Sign in on another device and enter the code. The code lasts 5 minutes; Ctrl-C cancels. This works for every account, including one that signs in with Apple and hides its email.
Prefer an email code? `npx -y curatively-mcp login --email`, then enter the email of your Curatively account and the 6-digit code it sends.
You need an account already — sign up in the app first; it creates your vault. The session is stored in `~/.curatively/credentials.json` and refreshes itself.
## Remote: claude.ai, ChatGPT, Codex, Cursor, Claude mobile
For apps that connect to a URL instead of launching a process, the same fourteen tools are served over Streamable HTTP with OAuth. You sign in with your own account and approve access in the browser; nothing to install.
Endpoint: `https://curatively.io/api/mcp`
- **claude.ai** — Settings → Connectors → Add custom connector → paste the endpoint, or open the prefilled form from <https://curatively.io/connect>. Free includes one custom connector. On Team or Enterprise an Owner adds it for everyone.
- **ChatGPT** — on chatgpt.com only; custom MCP apps are not available in the ChatGPT phone app. OpenAI lists Business, Enterprise and Edu (a workspace admin turns on Developer mode) and read-only access on Pro; Plus and Free are not listed. Add a custom MCP server and paste the endpoint.
- **Claude Code** — `claude mcp add --transport http curatively https://curatively.io/api/mcp`, then `/mcp` → Authenticate.
- **Codex** — `codex mcp add curatively --url https://curatively.io/api/mcp`, then `codex mcp login curatively`.
- **Cursor** — use the Add to Cursor link on <https://curatively.io/connect>, or add it by hand in `.cursor/mcp.json` (or the global one):
```json
{
"mcpServers": {
"curatively": { "url": "https://curatively.io/api/mcp" }
}
}
```
The remote server holds no secret and no copy of your data: your OAuth token is your own Supabase session, forwarded as you, and row-level security applies. When you connect, you choose **Read only** (the default: search, read, and suggestions for you to review) or **Read and save** (also saves, note edits, new vaults and your Direction). The database holds the connection to that choice whatever it calls, and no connection can publish or delete your saves or delete your account. Change a connection's access or disconnect it any time in Account → AI tools (<https://curatively.io/account/ai-tools>). The local server below is different: it is your own session on your own computer.
## Add to your agent (local)
These run the server on your own machine, over stdio: no network door, and the session file `npx -y curatively-mcp login` writes is the one they use. The remote recipes above are the same fourteen tools with nothing to install.
**Claude Code**
```sh
claude mcp add curatively -- npx -y curatively-mcp
```
**Claude Desktop** — in `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart:
```json
{
"mcpServers": {
"curatively": { "command": "npx", "args": ["-y", "curatively-mcp"] }
}
}
```
**Codex** — in `~/.codex/config.toml`:
```toml
[mcp_servers.curatively]
command = "npx"
args = ["-y", "curatively-mcp"]
```
**Cursor** — in `.cursor/mcp.json` (or the global one):
```json
{
"mcpServers": {
"curatively": { "command": "npx", "args": ["-y", "curatively-mcp"] }
}
}
```
Then ask for things the way you would say them: *"build the settings screen in the style of that dashboard I saved"*, *"what did I save this week"*, *"save this link"*.
## Teach Claude Code when to look (optional)
The server exposes the tools; the skill tells the agent when to reach for them and what to do with a save's image, palette and tags. Install it once:
```sh
npm i -g curatively-mcp
mkdir -p ~/.claude/skills && cp -r "$(npm root -g)/curatively-mcp/skill" ~/.claude/skills/curatively
```
## Tools
| Tool | What it does |
|---|---|
| `search_vault` | Semantic search in your own words; ranked, with a similarity score |
| `get_item` | One save with full metadata, the image itself, and a one-hour signed URL |
| `get_items` | Up to ten saves in one call, in the order asked, with pictures for the first four |
| `find_related` | Up to six saves nearest one of yours — the app's Related section, image-aware |
| `list_recent` | Your latest saves, newest first |
| `list_items` | Browse by format, source site, colour or date — the filter bar, paged |
| `save_item` | Save a photo, link and/or note — private, catalogued in the background |
| `update_note` | Replace the note you wrote on one save; returns the previous text |
| `get_inspiration_context` | Your active Direction, the references you chose, and what you said fit |
| `set_direction` | Sets or rewords your Direction in your words, so research can aim at it |
| `set_direction_status` | Pauses, completes or resumes a Direction |
| `submit_inspiration_batch` | Hands back up to five researched sources for you to review in the app |
| `list_vaults` | Your vaults — separate spaces for different kinds of saves — with their save counts and which one is home |
| `create_vault` | Makes a new private vault when you ask for one; asking for a name you have returns that vault |
**Vaults.** You may keep several vaults (say *Interiors* and *Site inspo*). Searching, listing and reading span every vault unless you name one — `search_vault`, `list_recent`, `save_item` and `get_inspiration_context` take an optional `vault` (a name or slug from `list_vaults`); `list_items` reads the home vault unless you name one. Saving goes to your home vault unless you name another, and the answer says where it landed. Every item carries a `vault` field with its vault's name. `get_inspiration_context` with a `vault` adds a compact reference pack of that vault — its recurring tags, palette, sources and newest catalogued samples — so "build this from my Site inspo vault" is one call. Free accounts keep three vaults; Plus makes as many as you need, and nothing you already have is ever taken away.
Enrichment (title, tags, colors, description) runs after a save, so a very recent item may come back bare and become searchable a little later.
## Resources
Tools are what the assistant decides to call. Resources are what **you** attach. In Claude Code, type `@curatively:` to put your Direction, your recent saves or one of your vaults into a message; in Claude Desktop, use the paperclip.
| Resource | What you attach |
|---|---|
| `curatively://direction` | Your active Direction, the references you chose, past verdicts and links already suggested — the same JSON `get_inspiration_context` returns |
| `curatively://recent` | Your 20 newest saves, across your vaults, with their tags, colors and descriptions |
| `curatively://vault/{slug}` | One vault as a reference pack — the same block `get_inspiration_context` returns for it. Listed once per vault, titled with its name; the slug never changes, so an attached vault survives a rename |
All are text only: a resource is attached whole, so pictures stay behind an explicit `get_item`. Hosts that do not support resources (ChatGPT today) simply see the tools.
## Photo attachments
Ask “save this photo to Curatively” with an attachment. The assistant must be able
to read the actual file bytes and call `save_item` with `image`:
```json
{
"image": {
"save_id": "11111111-1111-4111-8111-111111111111",
"mime_type": "image/jpeg",
"data": "<padded base64 of the photo file>"
},
"note": "Optional note"
}
```
Generate a fresh UUID for each intended save; reuse it with identical bytes,
link and note if a request fails or times out. Retrying completes the original
card instead of creating a duplicate. The server reports success only after
storage upload and finalization succeed; interrupted saves remain flagged until
retried. No existing photo is overwritten, and nothing is published.
JPEG, PNG and WebP are supported up to 5 MiB decoded. Convert HEIC to JPEG or
resize larger photos in the host before sending — on a Mac,
`sips -s format jpeg photo.heic --out photo.jpg`; a HEIC file is refused by name
with that command in the error. Send plain padded base64, not
a data URL, local path or invented bytes. A host that cannot read attachments or
send their bytes cannot use this feature. Client-specific argument limits may
require a smaller image. The file bytes are preserved, including embedded photo
metadata; remove metadata in the host first if desired.
Both local and remote servers use this same tool. Release the updated npm package
for local clients and deploy the rebuilt web Worker for remote clients; refresh
or reconnect existing MCP connections so they discover the new `image` argument.
## Inspiration
A Direction is one line about what you are making, exploring or looking for. Keep it in the app, or just tell your assistant — an assistant that can search the web can then research against it instead of asking you to explain the project again. Paste this:
> Read my active Curatively Direction and selected references. Find up to five worthwhile articles, images or examples that could help, including useful ideas from other fields. Explain why each fits and submit them to Curatively for review. Use real sources; don't save anything directly to my vault.
`get_inspiration_context` returns your Direction in your own words, the references you deliberately attached (title and link only — never your notes or images), your last 20 fit / not-fit verdicts and the links already suggested to you. It is private information leaving your account for the connected assistant; that is the trade for getting research aimed at the real brief. No Direction set yet is a normal answer, not an error.
`set_direction` is a write, and the answer to "no Direction set yet": describe the project to your assistant and it writes the brief in your words. It also rewords an existing one — and because a new wording retires the research still pending for the old one, a good assistant asks you first. One Direction is active at a time; `set_direction_status` pauses, completes or resumes one, and leaving the active state retires pending research the same way. Neither tool touches a reference sheet you attached in the app, and neither can delete a Direction.
`submit_inspiration_batch` is a write. It adds at most five cards to a private batch you review in the Curatively app — **nothing is saved to your vault automatically**. You save the ones you want, card by card; the rest expire. The assistant does its own searching with its own tools, so what comes back is only as good as the host's research, and Curatively marks every such card as host-reported rather than something it verified. Ten batches per account per day; re-sending the same `idempotency_key` returns the same batch instead of a duplicate.
## Configuration
| Variable | Purpose |
|---|---|
| `CURATIVELY_URL` | Project URL override (local stack, self-hosted) |
| `CURATIVELY_ANON_KEY` | Anon key override — publishable, never a secret |
| `CURATIVELY_CREDENTIALS` | Session file path override (defaults to `~/.curatively/credentials.json`) |
## Security, in plain language
- Your session lives in `~/.curatively/credentials.json`, readable only by you (`0600`). `npx -y curatively-mcp logout` revokes it and deletes the file.
- The server holds your session and the project's public anon key — never a service key. Row-level security in the database decides what it can read, exactly as for the app.
- It can insert private saves and private suggestions for you to review, and set or reword your Direction. It cannot publish or delete anything; the only thing it can change on a save is the note you wrote.
- Runs locally over stdio. No hosted relay, nothing in between your agent and your vault.
## Development
```sh
npm install
npm run typecheck && npm run lint && npm test
npm run build # dist/index.js
```
Against the local stack, point it with `CURATIVELY_URL=http://127.0.0.1:54421` and the local anon key from `supabase status`. `login` pairs through the web app, so add `CURATIVELY_SITE_URL=http://localhost:3000` (the local web dev server, with `pair-device` served) and approve at `localhost:3000/pair`; `login --email` reads its code from Mailpit.
## Links
- Curatively: <https://curatively.io>
- Connect guide: <https://curatively.io/connect>
- Issues: <https://github.com/Abaii/curatively-mcp/issues>
## License
MIT © ABZN LIMITED
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues