Installation

This guide covers installing ultrasync for use with Claude Code, OpenAI Codex CLI, and other MCP-compatible tools.

Prerequisites

ultrasync requires Python 3.12+ and uv for package management.

Install uv

If you don't have uv installed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew
brew install uv

# Or via pip
pip install uv

Install ultrasync

Install the ultrasync MCP server as a uv tool:

uv tool install ultrasync-mcp

This installs ultrasync globally and makes it available across all your projects.

Verify Installation

Check that ultrasync is installed correctly:

uv tool run --from ultrasync-mcp ultrasync --version

Configure Your MCP Client

Claude Code

Add ultrasync to your Claude Code MCP configuration. You can do this via the CLI or by editing your settings file directly.

Option 1: Using the CLI

claude mcp add ultrasync -- uv tool run --from ultrasync-mcp ultrasync mcp

Option 2: Manual Configuration

Add to your ~/.claude/.claude.json (user scope) or project .mcp.json:

{
  "ultrasync": {
    "type": "stdio",
    "command": "uv",
    "args": ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]
  }
}

OpenAI Codex CLI

Add to your codex.toml configuration:

[mcp_servers.ultrasync]
command = "uv"
args = ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]

Other MCP Clients

ultrasync works with any MCP-compatible client. The server command is:

uv tool run --from ultrasync-mcp ultrasync mcp

Index Your Project

After installation, index your codebase to enable semantic search:

cd /path/to/your/project
uv tool run --from ultrasync-mcp ultrasync index

The indexer will:

Scan your codebase for supported file types
Extract symbols (functions, classes, types)
Generate embeddings for semantic search
Store the index locally in .ultrasync/

Indexing Options

# Index with progress output
ultrasync index --verbose

# Index specific directories
ultrasync index src/ lib/

# Exclude patterns
ultrasync index --exclude "node_modules,dist,build"

# Force re-index (ignore cache)
ultrasync index --force

Optional: Enable Team Sync

To sync memories and context across your team, configure remote sync:

1. Get Your API Token

2. Configure Environment Variables

Claude Code - Add env to your MCP config:

{
  "ultrasync": {
    "type": "stdio",
    "command": "uv",
    "args": ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"],
    "env": {
      "ULTRASYNC_REMOTE_SYNC": "true",
      "ULTRASYNC_SYNC_URL": "https://mcp.ultrasync.dev",
      "ULTRASYNC_SYNC_TOKEN": "<your-api-token>",
      "ULTRASYNC_TOOLS": "search,memory,sync"
    }
  }
}

Codex CLI - Add to codex.toml:

[mcp_servers.ultrasync]
command = "uv"
args = ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]

[mcp_servers.ultrasync.env]
ULTRASYNC_REMOTE_SYNC = "true"
ULTRASYNC_SYNC_URL = "https://mcp.ultrasync.dev"
ULTRASYNC_SYNC_TOKEN = "<your-api-token>"
ULTRASYNC_TOOLS = "search,memory,sync"

Optional: Enable Secrets Detection

To prevent accidentally syncing sensitive data like API keys and credentials, install with the secrets extra:

uv tool install "ultrasync-mcp[secrets]"

This enables automatic scanning for potential secrets before syncing and will warn you about any detected credentials.

Environment Variables Reference

Variable	Default	Description
`ULTRASYNC_REMOTE_SYNC`	`false`	Enable team sync
`ULTRASYNC_SYNC_URL`	-	Sync server URL
`ULTRASYNC_SYNC_TOKEN`	-	Your API token
`ULTRASYNC_TOOLS`	`search,memory`	Enabled tool categories
`ULTRASYNC_INDEX_PATH`	`.ultrasync/`	Local index location
`ULTRASYNC_LOG_LEVEL`	`info`	Logging verbosity

Troubleshooting

uv not found

Ensure uv is in your PATH. After installation, you may need to restart your terminal or source your shell profile:

source ~/.bashrc  # or ~/.zshrc

Python version issues

ultrasync requires Python 3.12+. Check your version:

python --version

If needed, install a newer Python version via pyenv or your system package manager.

Permission errors

If you encounter permission errors during installation:

# Use --user flag or ensure proper permissions
uv tool install ultrasync-mcp --python-preference system

Index not updating

If changes aren't being detected, force a re-index:

ultrasync index --force

Or delete the local cache:

rm -rf .ultrasync/
ultrasync index

Next Steps

Configuration - Customize ultrasync settings

Installation

On this page