Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Developer resourcesbreadcrumb arrow Grafana MCP serverbreadcrumb arrow Clientsbreadcrumb arrow Codex CLI
Enterprise Open source

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

Bash 
codex mcp add grafana -- mcp-grafana

Add environment variables:

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 
[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 
[mcp_servers.grafana]
command = "mcp-grafana"
args = ["-debug"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "<your-token>" }

Docker setup

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 
# 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 
[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 
# Wrong - JSON-style
env = {"GRAFANA_URL": "http://localhost:3000"}

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

Read-only mode

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

Next steps