Documentation | Cortex MCP

Choose Your Installation Method

Fastest Way to Get Started

Just copy and paste one command. Works on macOS, Linux, and Windows.

macOS / Linux

curl -sSL https://raw.githubusercontent.com/syab726/cortex/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/syab726/cortex/main/scripts/install.ps1 | iex

Note: The installer will automatically:

Check Python 3.11+ is installed
Install cortex-mcp via pip
Configure Claude Code's mcp.json
Verify the installation

1

Install via pip

Requires Python 3.11 or higher.

pip install cortex-mcp

2

Verify Installation

Check that all dependencies are installed correctly:

cortex-mcp --check

Checking Cortex MCP installation...

  [OK] MCP SDK: 1.0.0
  [OK] ChromaDB: 0.4.x
  [OK] Sentence Transformers: 2.2.x
  [OK] PyYAML: 6.0
  [OK] aiofiles: 23.x

All dependencies installed correctly!

3

Configure Claude Code

Add Cortex to your Claude Code MCP configuration:

File location:

~/.claude/mcp.json

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "cortex_mcp"]
    }
  }
}

Tip: If you already have other MCP servers configured, just add the "cortex" entry to your existing mcpServers object.

4

Restart Claude Code

Restart Claude Code to load the new MCP server:

claude --mcp-restart

You're Ready!

Start a new conversation in Claude Code. Cortex will automatically detect your project and ask which scan mode to use.

First Use: Project Initialization

When you start a conversation in a new project, Cortex will ask you to choose a scan mode:

[CORTEX_INIT_PROTOCOL]

Cortex detected a new project. Choose initial scan mode:

1. [FULL] - Deep analysis (recommended for complex projects)

2. [LIGHT] - Quick scan (README, config, entry points)

3. [NONE] - Skip scanning

FULL Mode

Complete codebase analysis. Best for long-term projects. Takes more time initially.

LIGHT Mode (Recommended)

Scans key files only. Fast startup. Good for most projects.

NONE Mode

No initial scan. Context builds organically as you work.

Troubleshooting

Python version error

If you see "Python 3.11+ required":

# Check your Python version
python3 --version

# Install Python 3.11+ from python.org if needed

MCP server not loading

If Cortex doesn't appear in Claude Code:

Check ~/.claude/mcp.json syntax is valid JSON
Verify cortex-mcp is installed: pip show cortex-mcp
Run claude --mcp-restart
Try claude mcp list to see registered servers

Permission errors on macOS/Linux

If you see permission denied errors:

# Use pip with --user flag
pip install --user cortex-mcp

# Or use a virtual environment
python3 -m venv ~/.cortex-venv
source ~/.cortex-venv/bin/activate
pip install cortex-mcp

Need Help?

Check our FAQ or reach out for support

View FAQ GitHub Issues Contact Support

Installation Guide