How to Set Up Geneziz MCP Server with Claude Code

Why Connect Geneziz to Your AI Assistant?

You've spent hours curating bookmarks on X.com, starring repos on GitHub, and organizing everything into a structured knowledge base with Geneziz. But when you open your IDE to write code, that knowledge is invisible - locked away in a separate app.

The Model Context Protocol (MCP) changes this. It lets any AI assistant that supports MCP query your Geneziz knowledge base in real time, right from your terminal or chat interface.

This guide walks through setting up the Geneziz MCP server with Claude Code (the most popular MCP-compatible AI assistant), but the same steps work with Cursor, Windsurf, or any other MCP-aware tool.

Prerequisites

Before you start, make sure you have:

1. Geneziz installed with at least one sync completed (geneziz fetch + geneziz process run at least once)
2. A valid license key (GNZ- or GNZD- prefix - every license includes the MCP server)
3. Your knowledge directory populated with tools, articles, or bookmarks
4. Node.js 18+ (for running the MCP server)

You can verify your setup by running:

geneziz status

Look for non-zero counts in tools, articles, or bookmarks.

Step 1: Start the MCP Server

Geneziz's MCP server is built into the CLI. Open your terminal and run:

geneziz mcp

This starts the MCP server on stdio (standard input/output), which is how most AI assistants communicate with MCP servers.

You should see output like:

MCP server starting...
Listening on stdio...

The server exposes these tools to your AI assistant:

Step 2: Configure Claude Code for MCP

Claude Code has native MCP support. You need to add the Geneziz server to its configuration.

Option 0: geneziz mcp register (Recommended)

Let Geneziz do it. One command registers the MCP server with every AI client it detects on your machine - Claude Code included:

geneziz mcp register

It writes the geneziz server entry into each client's config (for Claude Code, ~/.claude.json) using the absolute path to your Geneziz executable plus a GENEZIZ_DATA_DIR env pin, so the server starts with no PATH setup and always finds your data directory. Only Geneziz's own entry is touched - other servers in the same file stay as they are, and a one-time backup is written before any change. Check what happened with:

geneziz mcp register --status

And undo it any time with geneziz mcp register --remove --all (only the Geneziz entries are removed). If you prefer to see or place the entry yourself, use one of the manual options below.

Option A: Via Claude Code Settings

1. Open Claude Code
2. Press / to open the command palette
3. Type MCP or Manage MCP Servers
4. Click Add Server
5. Enter:
   • Name: Geneziz
   • Command: geneziz mcp
   • Type: stdio
6. Click Save

Option B: Via .claude/settings.json

Create or edit ~/.claude/settings.json in your home directory:

{
  "mcpServers": {
    "geneziz": {
      "command": "geneziz",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Step 3: Test the Connection

Open a new Claude Code session (or start chatting in Cursor/Windsurf) and try:

"Search my knowledge base for articles about React performance optimization"

If everything is configured correctly, the AI assistant will call the search_knowledge tool, query your local knowledge base, and return relevant results - complete with titles, categories, and snippets.

Try these test queries:

• "What tools have I saved in my knowledge base?"
• "Show me recent articles about Python"
• "List all categories in my knowledge base"

How It Works Under the Hood

When you ask a question that triggers a tool call:

1. Claude Code sends a JSON-RPC request to the geneziz mcp process
2. The MCP server reads your viewer-index.json and knowledge files
3. Results are returned as structured data (titles, slugs, categories, content)
4. Claude Code synthesizes the results into a natural language answer

All of this happens locally - your data never leaves your machine. The MCP server reads directly from your knowledge directory using SQLite FTS5 full-text search or ChromaDB vector search (both included with every license).

Common Issues

"Command not found: geneziz"

Make sure Geneziz is installed globally or available in your PATH:

# If installed with pip
pip install -e ".[dev-tools]"
geneziz --help

# Or if using the repo directly
cd /path/to/geneziz
python -m geneziz mcp

"No tools found"

Run geneziz index first to generate the viewer index:

geneziz index
geneziz status  # Verify tools/articles > 0

"License error: no active license"

The MCP server is included with every Geneziz license - both GNZ- and GNZD- keys work - but it does require a valid, activated license. Make sure your key is entered and the device is activated, then check it:

geneziz license --check GNZ-YOUR-KEY-HERE

Port already in use

If another geneziz mcp process is running, kill it first:

# Find and kill existing process
pkill -f "geneziz mcp"
# Then restart
geneziz mcp

Next Steps

Once your MCP server is running and connected:

1. Add it to your AI assistant's startup config so it auto-connects every session
2. Try asking questions about your own bookmarks - you'll be surprised what you find
3. Combine with geneziz sync to keep your knowledge base fresh before every coding session

Sharing Notes

This post is part of the Geneziz blog series. If you found it useful, share it with a developer who's drowning in bookmarks.