This guide gets pyckle-mcp installed, connected to Claude Code, and running semantic search against your codebase in under five minutes.

Prerequisites

Claude Code CLI installed
Python 3.9+
A codebase to index

Step 1: Install pyckle-mcp

pyckle-mcp is the MCP server that handles indexing and search. Install it from PyPI into the Python environment Claude Code will use to launch it.

pip install pyckle-mcp

Confirm the install succeeded and note the path to the executable — you'll need it in the next step.

which pyckle-mcp

Try This

Install into a dedicated virtualenv if you run multiple MCP servers. Keeps dependencies isolated and makes upgrades straightforward.

Step 2: Add MCP Server to Claude Code Config

Claude Code reads MCP server definitions from ~/.claude/settings.json. You register pyckle-mcp there so Claude Code can launch it automatically at session start.

Open ~/.claude/settings.json and add the server under the mcpServers key:

{
  "mcpServers": {
    "pyckle-mcp": {
      "command": "pyckle-mcp",
      "args": [],
      "env": {}
    }
  }
}

If mcpServers doesn't exist yet, create it. If other servers are already listed, add pyckle-mcp alongside them — don't replace the existing entries.

Warning

Use the full absolute path to the pyckle-mcp binary if Claude Code launches in an environment where your shell PATH isn't available. Replace "command": "pyckle-mcp" with "command": "/full/path/to/pyckle-mcp".

Step 3: Index Your Codebase

Indexing walks your project directory, chunks the source files, generates embeddings, and stores them in ChromaDB. You run this once per project — or again after large structural changes.

Start a new Claude Code session in your project directory, then call index_codebase() via the tool interface:

index_codebase(path="/absolute/path/to/your/project")

A typical codebase produces around 6,500 chunks. Indexing takes 30–90 seconds depending on project size and machine. You'll see a completion count when it finishes.

Key Insight

The index is stored persistently in ChromaDB. You don't re-index every session — only when your codebase changes substantially. Check status any time with index_stats().

Step 4: Run Your First Semantic Search

Once indexed, search_code() accepts natural language queries and returns the most relevant chunks ranked by hybrid semantic + BM25 fusion scoring. You don't need to know exact function or file names.

search_code(query="authentication middleware")

Try a few queries that reflect how your codebase is structured — error handling, database connections, API routing. The results include file paths and line references so you can navigate directly to the code.

search_code(query="database connection pooling")
search_code(query="request validation logic")

Try This

Phrase queries as descriptions of behavior, not symbol names. "validates user input on form submit" finds more than "validate()" does.

Step 5: Verify the Integration Is Working

Run index_stats() to confirm the index is populated and token_stats() to see that your queries are registering. Both should return data after completing steps 3 and 4.

index_stats()
token_stats(last_n=5)

index_stats() returns the chunk count for your indexed codebase. token_stats(last_n=5) shows the last five search queries with token usage — a quick sanity check that the server is receiving and processing requests.

If either call returns empty or an error, check that pyckle-mcp appears in Claude Code's active MCP servers list and that the path in settings.json resolves correctly.

Key Insight

You can register multiple codebases under different names. Each call to index_codebase() with a distinct path creates a separate index — useful when working across multiple projects in the same Claude Code environment.

What's Next

Next Guide Your First Semantic Search → Next Guide Resume Work with Session Context → Next Guide Use One Index Across Multiple Tools →

Set Up Pyckle in Claude Code