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

1. Set your Karakeep environment variables:

bash

export KARAKEEP_API_KEY="your-api-key"
export KARAKEEP_SERVER_ADDR="https://your-karakeep.example.com"

1. 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.