# niv mcp

`niv mcp` lets an app that speaks MCP, such as Claude Code, Cursor or Claude Desktop, read a folder's notes, and read and change a Space's databases. It's a local server the app starts itself, on your computer.

**What your agent reads through niv goes to its AI provider, under that provider's terms. That includes notes from an encrypted Space: they're decrypted on this device, so the provider can read them. Database rows aren't end-to-end encrypted at all.**

## Set it up

```
niv mcp config --folder ~/Notes
```

It prints that warning, then what to give your app. The folder is always named, because an app can start anywhere, and it's never your home folder or above it.

## The tools

| Tool             | Does                                                                     |
| ---------------- | ------------------------------------------------------------------------ |
| `list_notes`     | Lists notes by path                                                      |
| `read_note`      | Reads a note, up to 256 KB of text, and says if it cut it                |
| `search_notes`   | Finds notes by words in their title or text, ignoring case. Not semantic |
| `list_databases` | Lists a Space's databases                                                |
| `query_rows`     | Reads rows, as `niv databases query` does                                |
| `insert_row`     | Adds a row                                                               |
| `update_row`     | Changes a row's cells                                                    |

**Notes are read-only here.** To change one, your agent edits its file, and `niv sync` or the app carries the change.

## What it needs

**Notes** need no sync, no keys and no network: after a sync, they're plain files in the folder. So each answer has `folder`, saying whether they're being synced. When nothing is syncing, it says when they last were: they may be behind the Space.

A note that's in iCloud and not downloaded is never fetched. It's listed, reading it says so, and a search says how many it skipped. A file over 4 MB isn't read as a note.

**Databases** need this computer signed in with `niv sign-in`. The first call opens your key file. On a Mac, or a Linux desktop with a login keyring, niv reads the passphrase from there, once you've said yes to remembering it at a terminal. Over SSH, or anywhere else, add `--passphrase-file <path>` to the app's config. See [Sign in and keys](/p/docs/sign-in-and-keys). Each database tool takes `space`, a name or an id, else this folder's Space.

## Several at once

Any number can run, beside `niv sync` and the app: notes read only files, and take no lock.

## When it runs

It does nothing until a tool is called, and ends when the app closes it.

---

Published with [Niv](https://niv.md/) in the Space Docs.
