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

Dry runs print complete current and planned file contents. Use --summary-only to show the affected paths and actions without printing file contents:

codex-mcp-eraser --summary-only

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. Repeat --project PATH to also check multiple projects' .codex/ directories:

codex-mcp-eraser --codex-home ~/.codex \
  --project /path/to/project-one --project /path/to/project-two

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