Browse the user guide

Codex

Connect OpenAI Codex to Shotomatic over MCP with one click or a config.toml entry, check that it works, and fix common problems.

Updated November 16, 2026

View Markdown
On this page

OpenAI Codex can use Shotomatic on your Mac or Windows PC through Shotomatic's local MCP server. Shotomatic is tested with Codex.

Connect with one click

  1. Open Shotomatic and go to Settings > AI agents (Command + ,, or Ctrl + , on Windows).
  2. Under Connect an agent, select Connect next to Codex (ChatGPT).

Shotomatic adds itself to ~/.codex/config.toml, turns on Let AI agents use Shotomatic, and allows Codex, so no approval card appears. Start a new Codex session to load the server. Codex (ChatGPT) appears in the list once Codex has created its settings folder on your computer.

Add it by hand

Turn on Let AI agents use Shotomatic in Settings > AI agents, install Node 18.3 or later, and add this to ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.shotomatic]
command = "npx"
args = ["-y", "shotomatic", "mcp"]

Start a new session. The first time Codex connects this way, Shotomatic shows an approval card; select Allow.

Check that it works

Ask Codex:

"Check Shotomatic's status and tell me what you can do with it."

A working setup answers with the Shotomatic version, whether Screen Recording and Accessibility are granted on a Mac, your plan and the free screenshots left today, whether the website browser is installed, and any capture already running.

If the tool is unavailable

  • Codex does not list Shotomatic. Start a new session after editing config.toml, and check that the [mcp_servers.shotomatic] table appears only once in the file.
  • Codex (ChatGPT) is missing from Settings. Open Codex once so it creates its settings folder, then reopen Settings > AI agents.
  • "MCP access is turned off." Turn on Let AI agents use Shotomatic in Settings > AI agents, then start a new session.
  • The agent waits for approval. Open Shotomatic and select Allow on the card.
  • npx is not found. This applies to the manual entry only. See the troubleshooting list for all clients.

On Windows, click once inside a Kindle book before you ask Codex to turn its pages; Kindle ignores key presses until its reading view has been clicked. Next, try a request from What agents can do.

Codex | User Guide | Shotomatic