Pocket MCP

A Model Context Protocol (MCP) server that turns PocketBase into a "Second Brain" for Claude Code. Capture knowledge, decisions, bugs, patterns, and more - then recall them with semantic search.

Features

• Session Management - Track work sessions with goals and outcomes
• Task Tracking - Manage project tasks with priorities, features, and progress stats
• Knowledge Capture - Save observations, decisions, bugs, code snippets
• Workflow Automation - Save and reuse repeatable procedures
• Semantic Search - AI-powered search using OpenAI embeddings
• Project Context - Quick access to project tech stack, decisions, patterns
• Knowledge Graph - Link related entities together
• Retrospectives - Generate insights from past sessions

New to the tools? Check out the Complete Usage Guide for detailed workflows and best practices.

---

Quick Start

Option 1: Claude Code Plugin (Recommended)

# 1. Add marketplace
/plugin marketplace add JaoChai/pocket-mcp

# 2. Install plugin
/plugin install pocket-mcp@jaochai-plugins

# 3. Configure (will prompt for credentials)

Option 2: Manual MCP Setup

Add to your project's .mcp.json:

{
  "mcpServers": {
    "pocket-mcp": {
      "command": "npx",
      "args": ["-y", "github:JaoChai/pocket-mcp"],
      "env": {
        "POCKETBASE_URL": "https://your-pocketbase-instance.com",
        "POCKETBASE_EMAIL": "admin@example.com",
        "POCKETBASE_PASSWORD": "your-password",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Then enable in .claude/settings.local.json:

{
  "enableAllProjectMcpServers": true
}

Setup PocketBase

Deploy PocketBase (self-host or use PocketHost, Elestio, etc.)

Then run the setup script to create collections:

git clone https://github.com/JaoChai/pocket-mcp.git
cd pocket-mcp
npm install

# Set environment variables
export POCKETBASE_URL="https://your-instance.com"
export POCKETBASE_EMAIL="admin@example.com"
export POCKETBASE_PASSWORD="your-password"

# Run setup
npm run setup-collections

---

Quick Reference: When to Use Which Tool

Event	Tools to Use
Start your day	get_pending_outcomes, get_lessons, get_project_context
Start new work	create_session, create_task, update_task(in_progress)
Need to find info	search_knowledge, semantic_search, find_workflow
Made a decision	capture_decision
Fixed a bug	capture_bug
Learned something new	capture_observation
Wrote reusable code	save_snippet
Finished work	update_task(done), generate_retrospective, end_session

See Complete Usage Guide for detailed workflows.

---

Available Tools (28 tools)

Session Tools (3)

Manage work sessions for tracking activities.

Tool	Description
create_session	Start a new work session with project and goal
end_session	End session with outcome (success/partial/failed) and summary
get_current_session	Get active session info

Task Tools (5)

Track project tasks with priorities and progress.

Tool	Description
create_task	Create a new task with title, description, feature, priority
update_task	Update task status, priority, or details
get_tasks	List tasks with filters (project, status, feature, priority)
get_project_progress	Get completion stats, tasks by feature, next-up items
delete_task	Delete or cancel a task (soft delete by default)

Task Statuses: pending, in_progress, done, blocked, cancelled

Priorities: critical, high, medium, low

Capture Tools (4)

Save knowledge and learnings.

Tool	Description
capture_observation	Save discoveries, patterns, insights, notes
capture_decision	Log decisions with context, options, and rationale
capture_bug	Record bugs with error message, solution, prevention
save_snippet	Store reusable code snippets with language and use cases

Outcome Tracking Tools (2)

Track decision outcomes for learning.

Tool	Description
record_decision_outcome	Record what happened after a decision was made
get_pending_outcomes	Find decisions older than N days that need outcome review

Workflow Tools (4)

Save and reuse repeatable procedures.

Tool	Description
save_workflow	Save a workflow with trigger, steps, and success criteria
find_workflow	Find workflow by describing what you want to do
get_workflow	Get full details including all steps
record_workflow_execution	Record that a workflow was executed

Search Tools (2)

Find knowledge in your Second Brain.

Tool	Description
search_knowledge	Full-text search across all collections
semantic_search	AI-powered similarity search using embeddings

Context Tools (3)

Quick access to project and user context.

Tool	Description
get_project_context	Get tech stack, recent decisions, bugs, patterns
get_preferences	Get user preferences (coding style, tools, workflow)
save_preference	Save a user preference with strength level

Relation Tools (3)

Build a knowledge graph.

Tool	Description
link_entities	Create relationship between two entities
get_relations	Get all relationships for an entity
suggest_relations	Auto-suggest relations based on shared tags

Relation Types: uses, caused, fixed_by, led_to, related_to, depends_on, inspired_by

Reflection Tools (2)

Learn from past experiences.

Tool	Description
generate_retrospective	Create retrospective with lessons and action items
get_lessons	Get lessons from past retrospectives

---

PocketBase Collections (14)

The setup script creates these collections:

Collection	Description
projects	Project information and tech stack
sessions	Work session tracking
tasks	Task tracking with priorities and features
areas	PARA method areas of responsibility
observations	Discoveries, patterns, insights, notes
decisions	Decision logs with rationale and outcomes
bugs_and_fixes	Error tracking and solutions
patterns	Design and architecture patterns
code_snippets	Reusable code snippets
workflows	Saved procedures and workflows
retrospectives	Session reviews and lessons
resources	Reference materials
relationships	Knowledge graph edges
user_preferences	User preferences
embeddings	Vector embeddings for semantic search

---

Environment Variables

Variable	Required	Description
POCKETBASE_URL	Yes	PocketBase instance URL
POCKETBASE_EMAIL	Yes	Admin email for authentication
POCKETBASE_PASSWORD	Yes	Admin password
OPENAI_API_KEY	Yes	OpenAI API key for embeddings
LOG_LEVEL	No	Log level (default: info)

---

Usage Examples

Session Management

# Start a session
Claude, start a session for "implementing user authentication"

# End with summary
Claude, end the session - we completed JWT auth and refresh tokens

Task Tracking

# Create tasks
Claude, create a task "Add password reset flow" with high priority

# Check progress
Claude, show me the project progress

# Update status
Claude, mark the authentication task as done

Knowledge Capture

# Capture observation
Claude, save this: "React Query handles cache invalidation automatically in mutation's onSuccess"

# Capture decision
Claude, record that we chose JWT over sessions because of scalability needs

# Capture bug fix
Claude, save this bug: TypeError on undefined - fixed by adding optional chaining

Workflow Automation

# Save a workflow
Claude, save this deployment workflow:
1. Run tests
2. Build the project
3. Deploy to staging
4. Run smoke tests

# Find a workflow
Claude, how do I deploy to production?

# Record execution
Claude, I just ran the deployment workflow successfully

Search Knowledge

# Full-text search
Claude, search for "authentication patterns"

# Semantic search
Claude, find knowledge related to "handling API errors gracefully"

Project Context

# Get project context
Claude, what do you know about this project?

# Get preferences
Claude, what are my coding preferences?

Retrospectives

# Generate retrospective
Claude, generate a retrospective for today's session

# Get lessons
Claude, show me lessons from past sessions

---

Installation Options

Option 1: Plugin (Easiest)

/plugin marketplace add JaoChai/pocket-mcp
/plugin install pocket-mcp@jaochai-plugins

Option 2: npx from GitHub

{
  "mcpServers": {
    "pocket-mcp": {
      "command": "npx",
      "args": ["-y", "github:JaoChai/pocket-mcp"],
      "env": { ... }
    }
  }
}

Option 3: From Source

git clone https://github.com/JaoChai/pocket-mcp.git
cd pocket-mcp
npm install
npm run build

---

Development

npm install           # Install dependencies
npm run build         # Build TypeScript
npm run dev           # Development mode with tsx
npm run setup-collections  # Setup PocketBase collections
npm test              # Run tests

---

Architecture

pocket-mcp/
├── src/
│   ├── index.ts          # Entry point (bin)
│   ├── server.ts         # MCP server with 28 tools
│   ├── config.ts         # Config validation (Zod)
│   ├── pocketbase/
│   │   ├── client.ts     # PocketBase client
│   │   └── collections.ts # Collection schemas
│   ├── tools/
│   │   ├── session.ts    # Session management
│   │   ├── tasks.ts      # Task tracking
│   │   ├── capture.ts    # Knowledge capture
│   │   ├── workflow.ts   # Workflow automation
│   │   ├── search.ts     # Full-text & semantic search
│   │   ├── context.ts    # Project context & preferences
│   │   ├── relate.ts     # Knowledge graph relations
│   │   └── reflect.ts    # Retrospectives & lessons
│   └── utils/
│       ├── embeddings.ts # OpenAI embeddings
│       └── logger.ts     # Logging (stderr for MCP)
├── scripts/
│   └── setup-collections.ts
└── dist/                 # Compiled output

---

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Credits

Built with:

• Model Context Protocol SDK
• PocketBase
• OpenAI API