Pocket Pick MCP Server

When adding items, you must provide a unique ID. If an ID already exists, the operation will fail.

Recommended ID Schemes:

• Descriptive IDs: Use meaningful names like python-sort-algorithm or css-flexbox-cheatsheet.
• Namespaced IDs: Use prefixes like py-, js-, or css- to categorize items.
• UUID-style IDs: Use standard UUIDs if you prefer automatically generated unique identifiers.

Pocket Pick requires explicit ID management for all new items. Follow these rules to ensure successful additions:

• Uniqueness: IDs must be unique across your entire database.
• Descriptive Naming: Use semantic IDs (e.g., my-project-config) instead of random strings to make item recall easier.
• Error Handling: If you attempt to add an item with an ID that is already in use, the server will return an error indicating a duplicate ID.

Pocket Pick uses a SQLite database to store knowledge. The primary table is POCKET_PICK and follows this structure:

Note on Tags: Tags are automatically normalized: they are forced to lowercase, whitespace is trimmed, and spaces or underscores are replaced with dashes.

CREATE TABLE if not exists POCKET_PICK {
    id: str,
    created: datetime,
    text: str,
    tags: str[],
}

To install Pocket Pick, ensure you have uv installed, then clone the repository and sync dependencies.

# Clone the repository
git clone https://github.com/indydevdan/pocket-pick.git
cd pocket-pick

# Install dependencies
uv sync

Use the claude mcp add command to register the Pocket Pick server with Claude Code.

If you are already in the pocket-pick directory:

claude mcp add pocket-pick -- \
    uv --directory . \
    run mcp-server-pocket-pick

Using a specific codebase path:

claude mcp add pocket-pick -- \
    uv --directory /path/to/pocket-pick-codebase \
    run mcp-server-pocket-pick

Using a custom database location:

claude mcp add pocket-pick -- \
    uv --directory /path/to/pocket-pick-codebase \
    run mcp-server-pocket-pick --database ./database.db

Verify installation:

claude mcp list

To ensure the MCP server is correctly installed and functioning, you can use the following validation steps:

1. Run Tests: Use uv run pytest to execute the test suite.
2. Check CLI Help: Run uv run mcp-server-pocket-pick --help to verify the command is recognized and the help menu displays correctly.

You can integrate Pocket Pick with Claude Code by adding a configuration to your project's .mcp.json file. This allows Claude Code to automatically detect the server when started in that directory.

Standard Configuration:

{
  "servers": {
    "pocket-pick": {
      "command": "uv",
      "args": ["--directory", "/path/to/pocket-pick", "run", "mcp-server-pocket-pick"]
    }
  }
}

Configuration with a custom database location:

{
  "servers": {
    "pocket-pick": {
      "command": "uv",
      "args": ["--directory", "/path/to/pocket-pick", "run", "mcp-server-pocket-pick", "--database", "./custom-database.db"]
    }
  }
}

When adding a new text-based item to your Pocket Pick knowledge base, you must now provide a unique id. This replaces the previous behavior of automatic UUID generation and allows for semantic, descriptive naming. If you attempt to use an ID that already exists in the database, the tool will return an error.

Parameters:

• id (string, required): A unique identifier for the item.
• text (string, required): The content to be stored.
• tags (list of strings, optional): Metadata tags for the item.
• db_path (Path, optional): The path to the SQLite database.

Add "claude mcp list" as a pocket pick item with ID "claude-mcp-list". tags: mcp, claude, code

When adding the content of a file to your Pocket Pick knowledge base, you must provide a unique id. This allows you to reference file contents using meaningful identifiers.

Parameters:

• id (string, required): A unique identifier for the file content.
• file_path (string, required): The path to the file to be added.
• tags (list of strings, optional): Metadata tags for the item.
• db_path (Path, optional): The path to the SQLite database.

The pocket_list_ids command allows you to retrieve a lightweight list of all item IDs stored in your Pocket Pick database. This is useful for verifying if a specific ID exists or for quickly scanning available content without downloading full item details. You can optionally filter the results by tags or limit the number of IDs returned.

Parameters

• tags (optional): A list of strings to filter results to only include items containing these specific tags.
• limit (optional): An integer specifying the maximum number of IDs to return. Defaults to 100.
• db (optional): The file path to the database. Defaults to ~/.pocket_pick.db.

# Example response
python-sort-algorithm
css-flexbox-cheatsheet
docker-cheat-sheet
api-design-patterns
git-workflow