# NoteMCP

**Save in two seconds. Find it by asking.**

[![smithery badge](https://smithery.ai/badge/notemcpx/notemcp)](https://smithery.ai/servers/notemcpx/notemcp)

NoteMCP is a hosted note-taking app with a first-class [Model Context
Protocol](https://modelcontextprotocol.io) surface. You capture notes by
typing, by voice, or through your phone's share sheet. Your AI assistant
searches, reads, writes and tags them — as tools, not as a pasted context dump.

This repository is the **public documentation** for that agent surface: the
tools, the security model, and where your data goes. The application source is
not open.

- **Website** — <https://notemcp.com>
- **MCP endpoint** — `https://notemcp.com/mcp`
- **Transport** — Streamable HTTP
- **Auth** — OAuth 2.1, authorization code + PKCE
- **Server version** — 0.5.0

Signup is free, and every tool below works on the free plan — what the free
plan limits is how far back through your collection the agent will read, not
what you can capture.

---

## Connect

NoteMCP is a remote server, so there is nothing to install. Point your client at
the endpoint and it will walk you through signing in.

### Claude

Add it from its listing in Claude's connector directory:
<https://claude.ai/directory/connectors/notemcp>.

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "notemcp": {
      "url": "https://notemcp.com/mcp"
    }
  }
}
```

### VS Code

`mcp.json` — note that VS Code uses `servers`, **not** `mcpServers`:

```json
{
  "servers": {
    "notemcp": {
      "type": "http",
      "url": "https://notemcp.com/mcp"
    }
  }
}
```

---

## The tools

Twelve tools. Five read, seven write. Full reference in
[TOOLS.md](TOOLS.md).

| Tool | Does | Read-only | Destructive |
| --- | --- | :---: | :---: |
| `search_notes` | Search text, tags, and saved link metadata | ✅ | |
| `list_recent_notes` | The stream, newest activity first | ✅ | |
| `get_note` | One note in full, plus its thread | ✅ | |
| `list_tags` | Every tag, with live note counts | ✅ | |
| `get_note_asset` | An image attached to a note | ✅ | |
| `create_note` | Write a new note, or continue a thread | | |
| `append_to_note` | Add markdown to the end of a note | | |
| `replace_in_note` | Change one span of text | | ⚠️ |
| `update_note` | Replace whole fields | | ⚠️ |
| `tag_note` | Add tags | | |
| `untag_note` | Remove tags | | ⚠️ |
| `delete_note` | Move to trash (recoverable) | | ⚠️ |

Two design rules shape all of them:

**Lists never carry bodies.** A captured photo is a multi-megabyte data URL, and
one of those in a list reply would blow out an agent's context window. Lists
return a label and a short preview; `get_note` returns the body; an embedded
photo is redacted to `![photo]` even there, and the bytes come from
`get_note_asset` only when an agent actually needs to look.

**Editing is a patch.** `replace_in_note` changes one span rather than
resending the note. Every write takes an optional `if_updated_at`, so a note
edited on your phone mid-compose produces a rejected write instead of a silent
overwrite.

---

## What the agent can and cannot do

See [SECURITY.md](SECURITY.md) for the full model. In short:

- It reaches **your notes only**, scoped by your authenticated user id inside
  the database itself — never by a parameter the agent supplies.
- It **cannot delete permanently.** `delete_note` is a soft delete; the app can
  recover it.
- It **cannot reach the open internet** on your behalf, with one narrow
  exception documented in [SECURITY.md](SECURITY.md).
- It **cannot rewrite the body of a note containing a photo**, because MCP only
  ever showed it `![photo]` — so a rewrite would destroy what it could not see.

Where your data goes, and which third parties touch it, is in
[DATA-FLOW.md](DATA-FLOW.md). The binding privacy policy is
<https://notemcp.com/privacy>.

---

## Example prompts

See [examples/prompts.md](examples/prompts.md).

---

## Repository contents

| File | What it is |
| --- | --- |
| [TOOLS.md](TOOLS.md) | Full tool reference with annotations |
| [SECURITY.md](SECURITY.md) | Auth, isolation, and blast radius |
| [DATA-FLOW.md](DATA-FLOW.md) | Which third parties see what |
| [examples/prompts.md](examples/prompts.md) | Prompts that exercise each tool |
| [server.json](server.json) | MCP Registry manifest |
| [CHANGELOG.md](CHANGELOG.md) | Changes to the agent surface |

## Support

<https://notemcp.com/support>