Pocket Assistant

You can run a Pocket Assistant MCP Server to store, organize, and retrieve research content using semantic vectors. It leverages ChromaDB for vector storage, supports multiple topics, and lets you query your saved content with natural language to power pocket-sized AI assistants.

How to use

You start by running the MCP server on your machine or in your environment. Once it is running, you interact with it through an MCP client to save research content, run semantic searches, and manage topics. The core capabilities include saving content to topic-specific vector databases, querying content with natural language, listing topics, getting topic information, and deleting topics when you no longer need them.

How to install

Prerequisites: ensure you have Python 3.11 or higher and access to the OpenAI API key for embeddings.

Option A: Install with uvx (recommended) and run the MCP server directly.

Option B: Install with uv and use a local installation.

Option C: Install with pip.

Option D: Install from source and set up the runtime via uv.

Follow these concrete commands to set up the server in different ways.

Configuration and startup details

The server requires two environment variables: OPENAI_API_KEY for embeddings and a base path for storing research databases. A typical setup stores data under a directory structure like POCKET_DB_PATH/pocket_chroma_dbs. You also provide a research database path for the runtime to locate its storage.

OPENAI_API_KEY=your-api-key-here
RESEARCH_DB_PATH=/path/to/data

CLI and runtime configuration (example)

You can configure the MCP client to launch the server locally with a CLI-based setup that points to the pocket agent MCP server and passes the required environment variables.

{
  "mcpServers": {
    "research-assistant": {
      "command": "uvx",
      "args": ["pocket-agent-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "POCKET_DB_PATH": "/path/to/data"
      }
    }
  }
}

Additional notes

The server uses OpenAI embeddings via the text-embedding-3-small model and stores vectors locally in the pocket_chroma_dbs directory under the base data path. It supports multiple topics, deduplication, and semantic search through natural language queries.

Security and maintenance

Keep your OpenAI API key secure and limit access to the machine hosting the MCP server. Regularly review topics and prune any outdated data to maintain efficient storage usage.

Available tools

save_research_data

Save a list of text snippets to the vector database under a specified topic for later retrieval and semantic search.

query_research_data

Query saved research content using a natural language prompt and return a ranked list of results from the chosen topic.

list_topics

List all topics with their document counts to understand the scope of stored content.

delete_topic

Remove a topic and all its associated vector data from storage.

get_topic_info

Get detailed information about a specific topic, including counts and storage location.