robotmcp--ros-mcp-server/docs/install/clients/codex-cli.md

Step 1: Codex CLI Setup

Codex CLI is OpenAI's CLI agent for software development. It supports MCP servers natively. If you don't have it yet, see the installation instructions.

1. Install uv

uv is needed to run the MCP server via uvx.

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

See the uv installation docs for other platforms or troubleshooting.

2. Add the MCP Server

Edit your Codex CLI configuration file at ~/.codex/config.json and add the MCP server:

{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uvx",
      "args": ["ros-mcp", "--transport=stdio"]
    }
  }
}

Tip: If you're having trouble with the config file, ask Codex to help set it up. Tell it that the command to run the MCP server is uvx ros-mcp and it can generate the correct configuration.

3. Verify the Setup

Start Codex CLI and ask it to connect to a robot:

codex

Connect to the robot on localhost using the ros-mcp server

The MCP server will attempt to reach a robot on the same machine. It should report that the IP is reachable but the rosbridge port is closed — this confirms the MCP server is set up correctly.

Tip: If your AI assistant can't find the ros-mcp server, exit and restart Codex CLI so it picks up the new configuration.

To complete the connection, set up rosbridge on your robot.

Next Step

Set up rosbridge on the machine where ROS is running: Step 2: Rosbridge Setup

---

Advanced

• HTTP transport — run the MCP server as a standalone HTTP service instead of stdio
• Alternate installation methods:
  • Install via pip — traditional pip install or install from source with pip
  • Install from source — for developers who need to modify the server code

---

Back to Installation Guide | Troubleshooting