Avogadro Desktop MCP Server

General Discussion
1

While we can provide more examples in the website, I think a lot of people are using LLM for “simple script” processing. So I’ve been thinking a bunch about providing a tool to help expose the current JSON-RPC automation to Codex, Claude Code, Cursor, etc.

To be up-front, I have some Claude Fable credits and was curious what it would do. (That, and the MCP protocol has been changing - the newest version uses JSON-RPC so it makes it much easier to implement.)

Avogadro MCP Plan

Key points:

Current gaps that matter for MCP:

  • No way to read anything back: no command list, no molecule contents, no atom count, no camera state, no “is a basis set loaded”. A client is blind as to what Avogadro can do or the current state.
  • saveGraphic renders at the on-screen widget size only and writes to disk.
  • Command descriptions are one translated sentence; no parameter names, types, or defaults anywhere machine-readable. The docs page is the only schema.
  • Python command scripts (Command extension, InterfaceScript) are menu-only; not reachable over RPC even though they already carry a userOptions JSON schema.
  • No graceful quit, no way to start Avogadro from a client.

Create a new avogadro-mcp project:

  • MCP’s standard local transport is stdio: the client spawns the server process. A GUI app cannot be that process. Avogadro would have to serve Streamable HTTP over QTcpServer instead, and then every client needs a URL and a running app before it can connect at all.
  • The MCP spec moves fast (transports, auth, elicitation, structured output). A pure-Python server updates with pip; the C++ app ships a few times a year.
  • The bridge is where “help me write a script” lives anyway: it can hand out docs, examples, and the command catalogue without Avogadro running.
  • Avogadro’s job stays small and stable: answer JSON-RPC, describe itself.

Cost: the user needs Python and avogadro-mcp installed. Mitigated by letting Avogadro itself install the MCP client config and, later, by running the server from Avogadro’s bundled pixi environment.

Open decisions

  1. Schema source of truth: start with the Python catalogue and migrate to commandSchema() (recommended), or go straight to C++ and accept that the MCP server has untyped tools until all plugin PRs land?
  2. Auto-launch: should the MCP server start Avogadro when it is not running (default on, with an env var to disable), or always require the user to have it open?
  3. Headless: is offscreen batch rendering in scope? It changes the “every .xyz in this directory” story from “with Avogadro open” to “from a cron job”, but needs a spike and may not work on Windows.
  4. quit gating: accept --testing (matches the docs) or add a clearer --allow-rpc-quit?
  5. Command script naming (§4.4): script:<Display Name> vs a slug; does a slug need to be stable across translations? (InterfaceScript::displayName is translatable; the script’s file stem is not.)
  6. Scene-plugin settings (labels, colours, radii): defer, or design a setDisplaySetting builtin now so the MCP tools can make publication figures without the mouse?
2

I really would like to get some feedback, but here would be my personal preferences:

  1. I’d start with a Python catalogue to start because it’s almost immediately useful. Users can install avogadro-mcp and then start things like “I want a screenshot of all the *.out files in this directory.”
  2. I’m conflicted about auto-launch. I really don’t like the idea of an LLM starting a program without telling me? But I also always have Avogadro running, so I’m not the best choice.
  3. I’d suggest we allow offscreen rendering where supported. At least Mac and Linux users get something.
  4. Again, I’m not sure how much I like an LLM quitting a program for me.
  5. I don’t have a good idea on whether we should be translating the names of plugins. Does ‘chiraltube’ translate?
  6. I think we want to add some display setting options - this would help general automation even without the MCP installed (e.g., change the current display settings, change colors of atoms, etc.)
3

I also know that some folks have strong views about LLM tools. All of those are valid.

I just want to recognize that I’m sure there are users of LLM code tools and adding these fairly minimal features should make it much easier for them to script their use of Avogadro.