Karakeep MCP server
# Karakeep MCP Server
This is the Karakeep MCP server, which is a server that can be used to interact
with Karakeep from other tools.
## Supported Tools
**Bookmarks**
- Searching bookmarks (`search-bookmarks`)
- Reading a bookmark (`get-bookmark`, `get-bookmark-content`)
- Listing the lists that contain a bookmark (`get-bookmark-lists`)
- Creating text and URL bookmarks (`create-bookmark`)
- Updating a bookmark (`update-bookmark`)
- Deleting a bookmark (`delete-bookmark`)
**Lists**
- Listing all lists (`get-lists`)
- Retrieving a single list (`get-list`)
- Creating a list (`create-list`)
- Updating a list (`update-list`) — name, icon, description, parentId, query, public; field constraints (length caps, smart-query validation) are inherited from the shared schema
- Deleting a list (`delete-list`) — child lists are NOT deleted with the parent; they become root-level lists
- Listing bookmarks in manual and smart lists (`get-list-bookmarks`)
- Adding and removing bookmarks from lists (`add-bookmark-to-list`, `remove-bookmark-from-list`)
**Tags**
- Listing tags with filters / pagination (`get-tags`)
- Retrieving a single tag with usage counts (`get-tag`)
- Renaming a tag (`update-tag`)
- Deleting a tag (`delete-tag`) — bookmarks that had the tag are not deleted
- Listing the bookmarks attached to a tag (`get-tag-bookmarks`)
- Attaching and detaching tags on bookmarks (`attach-tag-to-bookmark`, `detach-tag-from-bookmark`)
**Assets**
- Getting a temporary signed download URL for an asset (`get-asset`)
**Highlights**
- Listing highlights across all bookmarks (`list-highlights`)
- Listing highlights for a bookmark (`get-bookmark-highlights`)
- Retrieving a single highlight (`get-highlight`)
- Creating, updating, and deleting highlights (`create-highlight`, `update-highlight`, `delete-highlight`)
Currently, the MCP server only exposes tools (no resources).
## Usage with Claude Desktop
From NPM:
```json
{
"mcpServers": {
"karakeep": {
"command": "npx",
"args": [
"@karakeep/mcp"
],
"env": {
"KARAKEEP_API_ADDR": "https://<YOUR_SERVER_ADDR>",
"KARAKEEP_API_KEY": "<YOUR_TOKEN>",
"KARAKEEP_CUSTOM_HEADERS": "{\"CF-Access-Client-Id\": \"...\", \"CF-Access-Client-Secret\": \"...\"}"
}
}
}
}
```
From Docker:
```json
{
"mcpServers": {
"karakeep": {
"command": "docker",
"args": [
"run",
"-e",
"KARAKEEP_API_ADDR=https://<YOUR_SERVER_ADDR>",
"-e",
"KARAKEEP_API_KEY=<YOUR_TOKEN>",
"-e",
"KARAKEEP_CUSTOM_HEADERS={\"CF-Access-Client-Id\": \"...\", \"CF-Access-Client-Secret\": \"...\"}",
"ghcr.io/karakeep-app/karakeep-mcp:latest"
]
}
}
}
```
TDQS
Scored across 29 tools
Most tools map cleanly to a distinct resource+action (bookmark, list, tag, highlight, asset), and descriptions disambiguate the tricky pairs. However, the inverse-named pair get-bookmark-lists (lists containing a bookmark) vs get-list-bookmarks (bookmarks in a list) is easy to swap, and get-tags/get-tag plus list-highlights/get-bookmark-highlights sit close together.
Kebab-case verb_noun is used throughout, which is good, but the verb for collection retrieval is inconsistent: get-tags, get-lists, get-bookmark-lists use 'get' while list-highlights and get-list-bookmarks use 'list'/'get' in different orders. Noun ordering also flips between get-bookmark-lists and get-list-bookmarks, which undermines predictability in an otherwise uniform scheme.
At 29 tools the surface is on the heavy side, but the domain genuinely spans five resources (bookmarks, lists, tags, highlights, assets) with real CRUD, so most tools earn their place. A few could be collapsed (e.g. the collection-level getters) to trim the count.
Bookmarks, lists, tags, and highlights all have near-complete lifecycle coverage, including membership add/remove and search. The gaps are around assets: get-asset exists but nothing lists a bookmark's asset IDs or uploads assets, and there is no create-tag (tags only appear via attach), leaving minor dead ends agents must work around.