Skip to content

Installation

Context Teleport runs on Python 3.11+ and requires Git. There are three ways to install it, depending on your workflow.

Prerequisites

Before installing, make sure you have:

  • Python 3.11 or newer -- check with python3 --version
  • Git -- check with git --version
  • An MCP-compatible agent tool: Claude Code, OpenCode, Cursor, Gemini, or Codex

uvx runs Python tools on demand without installing them permanently. This is the recommended approach because it keeps your environment clean and always uses the latest version.

uvx context-teleport --help

That is it. No pip install, no virtual environment to manage. The uvx resolver downloads and caches the package automatically.

When you register with an agent tool, the MCP configuration uses uvx as the command, so the agent spawns Context Teleport the same way:

uvx context-teleport init --name my-project
uvx context-teleport register claude-code

How uvx registration works

After register, the MCP config file (e.g. .mcp.json for Claude Code) contains an entry that runs the MCP server via uvx. You do not need to activate anything -- the agent tool handles startup automatically.

Installing uv

If you do not have uv installed yet:

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

See the uv documentation for other methods.

Method 2: pip install

Install from PyPI into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install context-teleport

Verify the installation:

context-teleport --help

You should see the full CLI help with subcommands for init, register, status, knowledge, decision, skill, sync, and more.

Optional extras

Context Teleport ships with optional dependency groups for specific features:

Enables filesystem monitoring with watchdog for the context-teleport watch command. Without this, watch mode falls back to polling.

pip install context-teleport[watch]

Installs mkdocs-material and plugins for building the documentation site locally.

pip install context-teleport[docs]

Includes pytest, ruff, and anyio for running the test suite and linting.

pip install context-teleport[dev]

Method 3: From source

Clone the repository and install in editable mode. This is useful for contributing or running the latest unreleased code.

git clone https://github.com/Mauricio-xx/context-teleport.git
cd context-teleport
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Verify with:

context-teleport --help

Use --local when registering from source

When running from a source checkout, pass --local to the register command so the MCP config points to your local context-teleport binary instead of uvx:

context-teleport register claude-code --local

Without --local, the config will try to use uvx, which would pull the PyPI version instead of your local edits.

Running tests

pytest tests/ -v

The full suite has 930+ tests covering core logic, MCP tools, CLI, adapters, sync, EDA parsers, and source importers.

Verifying the installation

Regardless of install method, confirm everything works:

# Show version and available commands
context-teleport --help

# Initialize a test store
context-teleport init --name test-project

# Check store status
context-teleport status

You should see output confirming the store was initialized with a .context-teleport/ directory in your project root.

How the entry point works

Context Teleport uses a single binary (context-teleport) with smart dispatch:

  • Interactive terminal + arguments -- runs the CLI (Typer app)
  • Non-interactive stdin + no arguments -- runs the MCP server (FastMCP over stdio)

This means agent tools can spawn it as an MCP server by piping stdin, while you use the exact same command for CLI operations in your terminal. You never need to think about this -- register sets up the MCP config correctly, and you use the CLI directly.

Next steps

With Context Teleport installed, head to the Quickstart to initialize your first store and register it with your agent tool.