Skip to main content

AI assistants (MCP)

ohm mcp lets an AI assistant look at one server the way you would in the console: which instances are running and how they are doing, what their logs say, which jobs failed and why, how backups ended. It speaks the Model Context Protocol, so it works with Claude Desktop, Claude Code and any other client that can start an MCP server.

It is read-only. Every question the assistant asks is a read the console also makes, under an API key you issue for it, and the server refuses anything else. It cannot start, stop, back up, restore or change anything. Its read-only key cannot download exports, dumps or backups, and no issued key reads an Odoo user's two-factor code: see What an issued key cannot do.

What the assistant can read​

ToolWhat it answers
server_summaryThe server's identity, version, license, instance counts and the latest host resource sample
list_instancesEvery instance the key may see: id, name, host name, Odoo version and edition, state and status
instance_statusOne instance in full: its configuration, image, state, active database, tuning and quota
instance_healthThe instance's latest health report: every check's finding and its advice
instance_logThe last lines of the instance's Odoo log, its Nginx error log or its Nginx access log (200 by default, 5000 at most)
failed_jobsThe jobs that failed or were interrupted, newest first, for the server or one instance
job_status, job_logOne job, and the last lines of its log
list_backups, backup_outcomesThe instance's backup archives on disk, and how each instance's last backup ended
uptimeAvailability over 24 hours to a year, for every probed target or one instance
resource_usageWhere the CPU, memory and disk go, for the server or one instance
slow_queriesThe slowest statements over the last hour, the last day or since the last reset
alertsThe published alert events, newest first
fail2ban_bansThe current bans, and the instances they were provoked on
geoip_lookupWhat the server's GeoIP databases record about one address
access_checkWhether an instance's location rules can currently be decided

The assistant chooses which to ask, and names the instance by its id, its name or one of its host names. A list returns 20 rows unless it asks for more, and never more than 100.

Set it up​

Three steps: issue a key, store a connection on the machine the assistant runs on, and tell the assistant how to start ohm mcp.

1. Issue a read-only key​

Remote or localagainst pelmo
$ ohm apikey create --name claude --read-only --expires 2027-01-31

Or on Security > API keys, Issue a key, with Level set to Read-only. The key is shown once.

  • Add --surface api --surface geoip (in the console: switch on GeoIP under Surfaces as well) if the assistant should use geoip_lookup; without it that one tool is refused.
  • Add --instance <id> once per instance (in the console: pick them under Instances) to let the assistant see only those. Everything it lists, tails and reads is then limited to them.
  • Give the key an expiry (Expires), and a name (in the console, its Description) that says who holds it, so the list on Security > API keys tells you whose key it is when you revoke it.

2. Store a connection​

On the machine the assistant runs on, store a connection to the server with that key, as in Administering it from your own machine:

Local only
$ ohm connection add --name pelmo --url https://pelmo.example.com:5312

Paste the key when it is asked for. ohm mcp uses the stored connection, so the key never appears in the assistant's configuration.

3. Add the server to the assistant​

Claude Code (on the machine where ohm is installed):

Local only
$ claude mcp add ohm -- ohm mcp --server pelmo

Claude Desktop: open Settings > Developer > Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "ohm": {
      "command": "ohm",
      "args": ["mcp", "--server", "pelmo"]
    }
  }
}

Restart Claude Desktop. It starts ohm mcp itself, and the tools are offered in a new conversation.

ohm is a Linux tool. When Claude Desktop runs on Windows, install ohm in a WSL distribution, store the connection there, and let Claude Desktop start it through WSL:

{
  "mcpServers": {
    "ohm": {
      "command": "wsl.exe",
      "args": ["-d", "Debian", "--", "ohm", "mcp", "--server", "pelmo"]
    }
  }
}

On a Mac, start it on a Linux machine you can reach over SSH, where ohm and the connection are:

{
  "mcpServers": {
    "ohm": {
      "command": "ssh",
      "args": ["admin@jump.example.com", "ohm", "mcp", "--server", "pelmo"]
    }
  }
}

The SSH key must be loaded without a prompt: the assistant cannot type a passphrase.

What leaves the server​

What a tool answers goes to the assistant, and the assistant sends it to its model provider (for Claude, Anthropic) as part of the conversation. That includes whatever the logs say: an access log holds visitors' addresses, and an Odoo log can hold user names, email addresses and record contents.

  • Limit the key to the instances the assistant needs (--instance).
  • Ask about one instance at a time rather than letting the assistant read every log.
  • Revoke the key on Security > API keys when you are done with it.

No credential is ever returned: the reads the tools make report secrets as "set" or "not set" only, as the console does.

When it does not work​

  • The assistant says the server failed to start. Run the same command in a terminal: ohm mcp --server pelmo. It prints its start-up lines and then waits for the assistant; press Ctrl+C. Anything wrong (no such connection, the server not answering, a certificate it does not trust) is printed on the terminal and in the log under ~/.local/share/ohm/logs/.
  • A tool answers that the server refused this key. The question is outside the key's scope: the instance is not one it covers, or it needs the GeoIP surface.
  • ohm mcp names no server. Pass --server, or set a default connection with ohm connection default.

To have the server itself ask Claude about one instance, without an assistant of your own, use Diagnose on the instance's page.

Last updated on