Unofficial MCP-first skill for using Karakeep with AI agents. Use it to save, search, organize, tag, list, summarize, and highlight Karakeep bookmarks throug...
---
name: karakeep-mcp-first
description: Unofficial MCP-first skill for using Karakeep with AI agents. Use it to save, search, organize, tag, list, summarize, and highlight Karakeep bookmarks through MCP first, with CLI/API fallback only when needed.
metadata:
tags: bookmarks, bookmark manager, mcp, ai agents, productivity
openclaw:
envVars:
- name: KARAKEEP_API_KEY
required: true
description: The API key for your Karakeep instance.
- name: KARAKEEP_SERVER_ADDR
required: false
description: The server address for your Karakeep instance.
requires:
env:
- KARAKEEP_API_KEY
- KARAKEEP_SERVER_ADDR
bins:
- karakeep
primaryEnv: KARAKEEP_API_KEY
homepage: https://github.com/thethomasjfellows/karakeep-mcp-first-skill
links:
github: https://github.com/thethomasjfellows/karakeep-mcp-first-skill
video: https://youtu.be/WQNhRyYyl64
karakeep: https://karakeep.app
docs: https://docs.karakeep.app
cliHelp: karakeep --help
install:
- kind: node
package: "@karakeep/cli"
bins: [karakeep]
---
# Karakeep MCP-First
An unofficial Karakeep skill for AI agents that prefers MCP for normal work and keeps CLI/API fallback available for the edge cases MCP does not handle yet.
Use this skill when the user wants an agent to work with their Karakeep bookmarks: save links, search saved content, organize lists, apply tags, clean up duplicates, summarize research, or create meaningful highlights.
Video walkthrough: https://youtu.be/WQNhRyYyl64
## What It Does
- Uses Karakeep MCP first for normal bookmark, list, tag, and content workflows.
- Falls back to the Karakeep CLI only for unavailable MCP features, bulk work, debugging, migrations, dumps, or raw JSON verification.
- Uses the Karakeep API directly only when MCP and CLI do not expose the needed operation.
- Keeps highlights intentional instead of spraying annotations everywhere.
- Helps turn Karakeep from a passive bookmark manager into an AI-usable research and workflow system.
## Quick Setup
1. Run Karakeep and create an API key.
2. Configure the official Karakeep MCP server in your agent.
3. Install the optional CLI fallback if you want it:
```bash
npm install -g @karakeep/cli
```
4. Set your Karakeep environment variables:
```bash
export KARAKEEP_API_KEY="your-api-key"
export KARAKEEP_SERVER_ADDR="https://your-karakeep.example.com"
```
5. Restart your agent session and ask it to use `karakeep-mcp-first`.
## Tool Priority
Use tools in this order:
1. Karakeep MCP for normal work.
2. Karakeep CLI for fallback, debugging, bulk import/export, migrations, dumps, or raw JSON verification.
3. Karakeep API for unsupported operations, especially highlight creation.
4. Browser/manual workaround only when the other options are insufficient.
If you do not use MCP, briefly explain why.
## MCP Tools
Prefer MCP for:
- `search-bookmarks`
- `get-bookmark`
- `create-bookmark`
- `update-bookmark`
- `get-bookmark-content`
- `get-lists`
- `create-list`
- `add-bookmark-to-list`
- `remove-bookmark-from-list`
- `attach-tag-to-bookmark`
- `detach-tag-from-bookmark`
Do not verify with CLI unless there is a clear reason.
## Agent Behavior
- Search before creating when duplicate bookmarks might matter.
- Use lists for durable collections, projects, source libraries, and workflows.
- Use tags for reusable labels across lists.
- Reuse existing tags when possible and avoid near-duplicates such as `ai-tools`, `aitools`, and `ai tool`.
- Prefer lowercase tags such as `ai`, `research`, `reference`, `todo`, `read-later`, `dev`, `business`, `video`, or project-specific tags.
- Confirm before destructive deletes, broad archive operations, or large cleanup sweeps.
- Avoid printing API keys or local secrets.
## Meaningful Highlights
Do not create highlights by default. Create highlights only when they preserve the exact part of the content the user cares about.
Good reasons to highlight:
- Ingredients, steps, commands, requirements, definitions, warnings, compatibility notes, pricing, conclusions, or key evidence.
- One obvious passage that is basically the reason to save the bookmark.
Highlighting rules:
- Highlight the smallest useful passage.
- Prefer 1-3 highlights unless the user asks for more.
- Add a concrete note such as `Ingredients requested by the user` or `Core compatibility requirement`.
- Do not highlight text that is not present in the saved content.
MCP does not currently expose highlight creation. When highlighting is warranted, use MCP to retrieve the bookmark/content, then use the Karakeep API to create the highlight and explain that API fallback was used.
## CLI Fallback
Use the CLI only when MCP is unavailable, incomplete, or the task needs bulk/debug/raw JSON behavior.
Useful fallback commands:
```bash
karakeep whoami --json
karakeep bookmarks search "is:fav #work" --json
karakeep bookmarks get <bookmark-id> --include-content --json
karakeep dump --help
karakeep migrate --help
karakeep wipe --help
```
## More Detail
For search syntax, bookmark/list/tag concepts, and expanded workflow examples, read `references/karakeep-details.md` when needed. Do not load it unless the task needs those details.
don't have the plugin yet? install it then click "run inline in claude" again.