---
title: "Codex CLI | Grafana documentation"
description: "Set up the Grafana MCP server for the OpenAI Codex CLI."
---

# Codex CLI

This guide helps you set up the `mcp-grafana` server for the OpenAI Codex CLI.

## Prerequisites

- Codex CLI installed (`npm install -g @openai/codex`)
- Grafana 9.0+ with a service account token
- `mcp-grafana` binary in your PATH

## Important: TOML format

Codex uses **TOML** configuration, not JSON. Configuration file: `~/.codex/config.toml`

## Configuration

### CLI setup (recommended)

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
codex mcp add grafana -- mcp-grafana
```

Add environment variables:

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
codex mcp add grafana \
  --env GRAFANA_URL=http://localhost:3000 \
  --env GRAFANA_SERVICE_ACCOUNT_TOKEN=<your-token> \
  -- mcp-grafana
```

### Manual configuration

Create or edit `~/.codex/config.toml`:

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
[mcp_servers.grafana]
command = "mcp-grafana"
args = []
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
```

**Note:** Use `mcp_servers` (underscore, not hyphen).

## Debug mode

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
[mcp_servers.grafana]
command = "mcp-grafana"
args = ["-debug"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
```

## Docker setup

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
[mcp_servers.grafana]
command = "docker"
args = ["run", "--rm", "-i", "-e", "GRAFANA_URL", "-e", "GRAFANA_SERVICE_ACCOUNT_TOKEN", "grafana/mcp-grafana", "-t", "stdio"]
env = { GRAFANA_URL = "http://host.docker.internal:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
```

## Verify configuration

Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```bash
# List configured servers
codex mcp list

# Show specific server config
codex mcp get grafana

# Start Codex and test
codex
```

Then ask: “List my Grafana dashboards”

## Timeout settings

If Grafana operations take time, increase timeout:

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
[mcp_servers.grafana]
command = "mcp-grafana"
args = []
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
startup_timeout_ms = 20000
tool_timeout_ms = 120000
```

## Troubleshooting

**Server not found in Codex:**

- Verify TOML syntax (no trailing commas, use `=` not `:`)
- Check key is `mcp_servers` not `mcp-servers`
- Restart Codex after configuration changes

**Config shared across CLI and IDE:** Codex CLI and VS Code extension share `~/.codex/config.toml`. A syntax error breaks both.

**Common TOML mistakes:**

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
# Wrong - JSON-style
env = {"GRAFANA_URL": "http://localhost:3000"}

# Correct - TOML-style
env = { GRAFANA_URL = "http://localhost:3000" }
```

## Read-only mode

toml ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```toml
[mcp_servers.grafana]
command = "mcp-grafana"
args = ["--disable-write"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }
```

## Next steps

- [Set up](../../set-up/) for other install options.
- [Configure authentication](../../configure/authentication/) for Grafana credentials.