ContextKeeper MCP Server

![npm version](https://www.npmjs.com/package/@ondrahracek/contextkeeper-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for ContextKeeper - integrates your context items with AI assistants like Cursor, Claude Desktop, and others.

What it does

This MCP server allows AI assistants to read and modify your ContextKeeper items directly through natural language. No need to manually switch between your editor and the terminal.

Tools

| Tool | Description | CLI Equivalent | |------|-------------|----------------| | list_context_items | List all context items with ID, content, project, tags, and status | ck list | | add_context_item | Add a new context item | ck add | | mark_context_done | Mark a context item as completed | ck done | | get_context_status | Get a quick summary (counts, projects, tags) | ck status | | search_context_items | Search context items by query string and/or tags | ck search | | remove_context_item | Remove (archive) a context item by ID | ck remove | | edit_context_item | Edit an existing context item's content and/or tags | ck edit | | sync_context_items | Trigger a sync of context items to AI agent files | ck sync |

Naming Convention

All tools follow MCP best practices:

snake_case: list_context_items, add_context_item
Verb-first: get_context_status, mark_context_done
Consistent plural: All use context_items (except status)
Aligned with CLI: Each tool maps directly to a ck command

Prerequisites

ContextKeeper CLI (ck) installed and on your PATH
Node.js 18 or later
npm or yarn

Installation

Option 1: npx (No install)

npx @ondrahracek/contextkeeper-mcp

Option 2: From Source

git clone https://github.com/ondrahracek/contextkeeper-mcp.git
cd contextkeeper-mcp
npm install
npm run build

Configuration

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "contextkeeper": {
      "command": "npx",
      "args": ["-y", "@ondrahracek/contextkeeper-mcp"]
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "contextkeeper": {
      "command": "node",
      "args": ["/path/to/contextkeeper-mcp/build/index.js"]
    }
  }
}

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contextkeeper": {
      "command": "npx",
      "args": ["-y", "@ondrahracek/contextkeeper-mcp"]
    }
  }
}

Usage Example

In Cursor's chat, you can say:

@contextkeeper What's my current context?

Claude will respond with your active items:

[
  {
    "id": "bc2839",
    "fullId": "bc2839b5-6a8b-4b2a-9e1e-7b5c4d3e2f1a",
    "content": "change tokens - find in whatsapp with...",
    "project": "",
    "tags": ["whatsapp"],
    "completedAt": null,
    "createdAt": "2026-02-08T21:25:00Z"
  }
]

Or:

@contextkeeper Add "review security middleware"

Claude will add the item and confirm.

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

Architecture

contextkeeper-mcp/
├── src/
│   ├── index.ts       # MCP server entry point
│   ├── helpers.ts     # CLI wrapper functions
│   └── types.ts       # TypeScript type definitions
├── build/             # Compiled JavaScript output
└── package.json

License

MIT - see LICENSE for details.

Contributing

Contributions welcome! Please open issues or PRs on GitHub.

ContextKeeper MCP Server