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:

npm install -g @karakeep/cli

4. Set your Karakeep environment variables:

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:

karakeep whoami --json
karakeep bookmarks search "is:fav #work" --json
karakeep bookmarks get \x3Cbookmark-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.