---
title: "Connect AI tools to Keep Markdown over MCP | Keep"
description: "Let Claude, Codex, Cursor, OpenCode, Pi, VS Code, and other MCP clients save and search Notes and Items in Keep."
canonical: "https://keep.md/docs/mcp"
language: "en"
---

# Connect an AI client to Keep over MCP

Let Claude, Codex, Cursor, OpenCode, Pi, VS Code, and other MCP clients save and search Notes and Items in Keep.

The Keep MCP server lets AI tools save links as Markdown, search Notes and saved Items together, read them, and update Notes. It works with remote MCP clients such as Claude Code, Claude Desktop, Codex, Cursor, OpenCode, Pi, and VS Code.

Point your MCP client at this endpoint:

`https://keep.md/mcp`

The first time your AI client connects, it will open a browser window to sign in and authorize access to your account.

Your client renews access in the background after that first sign-in. The connection stays active until you disconnect it, revoke its credentials, or reset the client. You should not need to sign in again on a schedule.

## Client setup

Run this command to add Keep to Claude Code.

```
claude mcp add --transport http keep https://keep.md/mcp
```

## What connected AI can do

Once connected, your AI tool can save Items, search your Keep library, read and update Notes, attach supporting Items, and manage sources. Search results stay short until the client opens a specific Note or Item. Account limits still apply.

`search_context` returns a Note revision and relevant line range when available, so the client can go straight to that exact slice. Otherwise `get_note` returns an overview by default, then the client can search within that revision. It requests `view: full` only when bounded reads are not enough. Reads do not use Note credits. Creating a Note uses one credit. Editing an existing Note does not use another credit.

`get_item` follows the same pattern. It returns an overview by default, then supports `view: search`, `view: lines`, or an explicit `view: full`. Highlights and media are separate bounded pages. Note tools return a `webUrl` that opens the note in Keep, plus an `apiUrl` for clients that need the complete Note response.

| tool | description |
| --- | --- |
| search\_context | Search Markdown Notes and saved Items together |
| get\_note | Read a Note with optional sources and recent history |
| create\_note | Create a Markdown Note |
| update\_note | Append at the latest revision, replace content, or update Note metadata |
| attach\_item | Attach an Item or highlight to a Note |
| save\_item | Save a URL as an Item with extracted Markdown |
| extract\_item | Run content extraction again for an Item |
| search\_items | Search items by keyword and semantic similarity |
| list\_items | List saved items with optional filters |
| get\_item | Read an Item overview, search window, line slice, or full document |
| list\_item\_highlights | List one page of Item highlights |
| list\_item\_media | List one page of ordered Item media references |
| get\_highlight | Get a single highlight by id |
| update\_item | Update title, notes, tags, or status of an item |
| whoami | Get the current account and plan details |
| list\_sources | List your content sources and subscriptions |
| add\_source | Add a content source like RSS, YouTube, X, or email |
| remove\_source | Remove a source |
| get\_stats | Get usage stats for your account |
| list\_inbox | Get unprocessed items from the inbox |
| list\_item\_changes | List item change events for delta sync |
| mark\_done | Mark inbox items as processed so they leave the inbox |

Use `get_item` with `includeMedia` when a few saved images could affect the answer. The result adds one `mediaPage`. Use `list_item_media` to continue from its `nextOffset` without loading the full manifest.

`list_sources` returns a compact status manifest without configuration, tag rules, or internal cursors. MCP does not provide an option to reveal source configuration.

## Access requested by MCP

The connection screen lists the access requested by the client. Keep can grant these scopes:

| Scope | Access |
| --- | --- |
| `profile` | Account name, plan, and usage |
| `items.read` | Search and read Items and Markdown |
| `items.write` | Save and update Items |
| `notes.read` | Search and read Notes |
| `notes.write` | Create and update Notes |
| `feed.read` | Read unprocessed Feed Items |
| `feed.write` | Mark Feed Items as processed |
| `sources.read` | List sources |
| `sources.write` | Add or remove sources |

The client receives only the scopes approved for that connection. Remove the Keep server from your AI client when it no longer needs access.

## Shared Note changes

MCP clients use the same Notes as the app and CLI. Append mode uses the latest revision automatically and preserves concurrent appends. Pass `expectedRevision` to pin an append when a stale revision should fail. Replacement and metadata modes still require `expectedRevision`, so they cannot overwrite a newer change.

Use `update_note` with `mode: metadata` when the body should stay unchanged. Metadata mode rejects `bodyMarkdown`. Append mode accepts Markdown only and does not need `expectedRevision`. It rejects title or metadata fields. Replace mode can change the body, title, and metadata together.

Fields omitted from an update stay unchanged. Pass an empty `tags` array to remove every tag. Pass `null` for `project`, `repository`, `kind`, or `state` to clear that field. The `properties` object contains custom metadata only, so changing it does not change those first-class fields.

Every successful write returns a compact receipt with Note and revision coordinates, never the Markdown body. It includes a compact `metadataDiff` that lists added and removed tag slugs and the before and after values for Project, kind, or state when they changed.

The trusted MCP client name appears in Note history. See [Connected agents](https://keep.md/docs/agents) for the collaboration rules.

## Need something different?

If you want to integrate Keep into your own app or script, check the [API](https://keep.md/docs/api) or [CLI](https://keep.md/docs/cli) instead. To keep another system in sync, use the [API keys](https://keep.md/docs/api-keys) with `/items/changes` for polling or [Webhooks](https://keep.md/docs/webhooks) for push delivery.