ContextKeeper MCP Server

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.