Repomix

You can run Repomix as a Model Context Protocol (MCP) server to let AI assistants pack, analyze, and interact with your codebase directly without manual file preparation. This enables streamlined AI-assisted code analysis, rapid exploration of remote repositories, and secure, structured data exchanges that preserve context for large projects.

How to use

To use the MCP server, start Repomix in MCP mode and connect your AI assistant or client. The MCP server exposes tooling that lets AI assistants pack local or remote repositories, attach packed outputs, read files securely, grep within outputs, read directories, and fetch packed outputs for analysis. Your AI tool can then request pack operations and analyze the resulting consolidated data without you prelisting files.

How to install

Prerequisites: you need Node.js (for the CLI and library usage) or Docker if you prefer containerized execution.

Install options for running in MCP mode include using npx or Docker. Use the commands below in your terminal.

# Run MCP server directly with npx (no installation required):
repomix --mcp

# Start MCP server via Docker (recommended if you prefer containerized runs)
docker run -v .:/app -i --rm ghcr.io/yamadashy/repomix --mcp

# If you want to install locally and run from Node
npm install -g repomix
repomix --mcp

# Alternative: run via Docker with explicit MCP command
# (uses the docker-based MCP server entry shown in examples)
docker run -v .:/app -i --rm ghcr.io/yamadashy/repomix --mcp

Configuration and operation notes

When running as an MCP server, you typically point your MCP-compatible client at the local process or a container that exposes the MCP endpoints. You can customize how packing happens by using flags that control compression, file inclusion, git context, and security scans. The MCP server exposes tools to pack codebases, attach packed outputs, pack remote repositories, read packed outputs, grep within outputs, read files, and list directory contents.

MCP commands to run (stdio configurations)

The MCP server can be started via a direct runtime command. Use the following complete stdio configuration when you run locally with npx.

{
  "name": "repomix_mcp",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "repomix", "--mcp"]
}

Alternative: Docker-based MCP server configuration

You can also run the MCP server in a Docker container. Use this configuration to start the Docker-based MCP server.

{
  "name": "repomix_docker_mcp",
  "type": "stdio",
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/yamadashy/repomix",
    "--mcp"
  ]
}

What you can do with the MCP server

Pack a local codebase for AI analysis, pack a remote repository, attach an existing packed output, search within a packed output, read individual files, and read directory contents. These operations enable AI assistants to analyze code, generate documentation, review architecture, or perform targeted refactors with full context.

Security and safety considerations

The MCP server integrates security checks during packing, including scanning for sensitive information. When using the MCP server, ensure you respect your organization's security policies and avoid exposing secrets through outputs that are shared with AI tools.

Troubleshooting tips

If the MCP server does not respond, verify the runtime command and ensure the port or IPC channel used by your MCP client is accessible. Check that you are using the exact command and arguments shown in the configuration examples. If you switch between npx and Docker, make sure the container or global installation is properly started with the --mcp flag.

Examples

Basic MCP start with local npx: run the MCP server locally using npx and connect your AI tool to it.

repomix --mcp

Available tools

pack_codebase

Package a local code directory into a consolidated XML file for AI analysis, with optional compression and selective inclusion.

attach_packed_output

Attach an existing Repomix packed output file for AI analysis, supporting either a directory containing repomix-output.xml or a direct XML file path.

pack_remote_repository

Fetch, clone, and package a remote GitHub repository into a consolidated XML file for AI analysis, with optional compression and inclusion/exclusion patterns.

read_repomix_output

Read the contents of a Repomix-generated output file, supporting partial reads by line ranges for large files.

grep_repomix_output

Search a Repomix output file using JavaScript RegExp patterns with optional context lines and case sensitivity options.

file_system_read_file

Read a file from the local file system with security validation to prevent access to sensitive information.

file_system_read_directory

List the contents of a directory with a clear indication of files vs. subdirectories and safe traversal.