# Karakeep MCP First

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

- Skill: `lord1egypt/karakeep-mcp-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lord1egypt/karakeep-mcp-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lord1egypt/karakeep-mcp-first/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Lord1Egypt (https://skillmd.com/u/lord1egypt)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/lord1egypt/karakeep-mcp-first

---


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