Claude Integration

Configure ContextFS MCP server for Claude Desktop and Claude Code

Prerequisites

1.Python 3.9+ - Required for running ContextFS
2.Claude Desktop or Claude Code CLI - The client application
3.uv (recommended) or pip - Python package manager

Installation

Option 1: Using uv (Recommended)

uv runs ContextFS directly without permanent installation:

uvx contextfs

Option 2: Using pip

Install ContextFS globally:

pip install contextfs

Claude Desktop Configuration

1. Locate your Claude Desktop config file

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Add ContextFS MCP server configuration

Add the following to your config file:

{
  "mcpServers": {
    "contextfs": {
      "command": "uvx",
      "args": ["contextfs"]
    }
  }
}

If you installed with pip instead, use:

{
  "mcpServers": {
    "contextfs": {
      "command": "contextfs"
    }
  }
}

3. Restart Claude Desktop

Quit and reopen Claude Desktop to load the new MCP server configuration.

Claude Code CLI Configuration

1. Create or edit your MCP settings file

Create a .mcp.json file in your project root or home directory:

{
  "mcpServers": {
    "contextfs": {
      "command": "uvx",
      "args": ["contextfs"]
    }
  }
}

2. Verify the configuration

Run the /mcp command in Claude Code to see connected servers:

/mcp

Environment Variables (Optional)

Configure ContextFS behavior with environment variables. Add these to the env block in your MCP config:

{
  "mcpServers": {
    "contextfs": {
      "command": "uvx",
      "args": ["contextfs"],
      "env": {
        "CONTEXTFS_DATA_DIR": "~/.contextfs",
        "CONTEXTFS_LOG_LEVEL": "INFO",
        "CONTEXTFS_CHROMA_HOST": "localhost",
        "CONTEXTFS_CHROMA_PORT": "8000"
      }
    }
  }
}

Common Variables:

CONTEXTFS_DATA_DIR - Directory for storing memories (default: ~/.contextfs)
CONTEXTFS_LOG_LEVEL - Logging verbosity: DEBUG, INFO, WARNING, ERROR
CONTEXTFS_CHROMA_HOST - ChromaDB server host (empty for embedded mode)
CONTEXTFS_CHROMA_PORT - ChromaDB server port (default: 8000)

Verify Installation

After configuration, verify ContextFS is working by asking Claude:

"List my recent memories using contextfs_list"

Claude should respond with a list of memories (or indicate the memory store is empty if new).

Available MCP Tools

contextfs_save

Save memories with type and tags

contextfs_search

Hybrid semantic + keyword search

contextfs_list

List recent memories

contextfs_recall

Recall a specific memory by ID

contextfs_evolve

Update memory with history tracking

contextfs_link

Create relationships between memories

contextfs_index

Index a repository codebase

contextfs_sessions

List saved conversation sessions

Troubleshooting

MCP server not appearing

Ensure your config file is valid JSON. Use a JSON validator if unsure. Also verify the command path is correct - try running uvx contextfs --version in your terminal.

Permission errors

On macOS/Linux, ensure the contextfs command is executable. If using pip install with sudo, the command should be available system-wide.

ChromaDB connection issues

If you see "Collection not found" errors, try reconnecting the MCP server (use /mcp in Claude Code). ChromaDB caches collection references.

Next Steps

Now that ContextFS is configured, try these commands:

• Initialize a repo: contextfs index init
• Index your codebase: contextfs index index
• Save your first memory: Ask Claude to "save a memory about this project"