Codex MCP eraser

A Python command-line tool that removes user-configured MCP server tables and hooks from Codex CLI configuration. It does not modify plugin settings or managed policies. Requires Python 3.11 or later.

Install

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install the package inside it:

python -m pip install codex-mcp-eraser

Use

The default is a dry run. Review the reported files before applying changes:

codex-mcp-eraser
codex-mcp-eraser --apply

Applying changes prompts for confirmation. Add --yes to skip that prompt:

codex-mcp-eraser --apply --yes

By default, the tool checks CODEX_HOME or ~/.codex. Use --codex-home PATH to select another Codex configuration directory. Add --project PATH to also check that project's .codex/ directory:

codex-mcp-eraser --codex-home ~/.codex --project /path/to/project

The tool removes only the MCP server named sheriff from config.toml and removes hooks.json in the checked directories. Other configured MCP servers are preserved. Before applying changes, it creates a backup under the user Codex home directory with restricted permissions. It does not modify plugin settings or managed policies.

Run from a checkout

After installing the package in the active virtual environment, you can also run it as a module:

python -m codex_mcp_eraser

The source checkout includes codex_mcp_eraser_launcher.py and the legacy eraser.py launcher.

Development

With the virtual environment active, run the unit tests with:

python -m unittest discover -s tests -v

Build and check the package with the repository script (it creates a temporary virtual environment for the build):

./build-package.sh