Skill: thethomasjfellows/karakeep-mcp-first (version 1.1.0)

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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)