Use plexosdb as an MCP Server

This guide shows how to run the PlexosDB MCP server and verify it is working.

What the server provides

The server exposes a curated set of 29 tools, grouped in categories similar to toolsets:

  • Session: health, create_empty_session, open_xml_session, close_session

  • Discovery: list_objects_by_class, list_object_memberships, list_child_objects, list_parent_objects, get_object_properties, iterate_properties, list_classes, list_collections, list_scenarios, list_models, list_scenarios_by_model, list_valid_properties, list_reports, list_units, query_readonly

  • Edit: add_object, add_membership, add_property, add_scenario, update_object, delete_object, delete_property

  • Export: save_xml, to_csv

  • Admin: get_server_config

Not every PlexosDB method in db.py is exposed as an MCP tool. Expose methods in curated batches so the public MCP interface remains stable and easy to support.

1) Install dependencies

Install the package you need:

  • Core library only:

uv add plexosdb

  • MCP server package (includes MCP CLI entrypoint):

uv add plexosdb-mcp

For local development from this repository:

uv sync --all-groups

2) Start the MCP server

Happy path — run from a published package using uvx:

uvx plexosdb-mcp

Safe path — read-only mode (recommended for untrusted prompts/hosts):

uvx plexosdb-mcp --read-only

Smoke checks — verify the server is reachable without starting the MCP daemon:

uvx plexosdb-mcp health
uvx plexosdb-mcp --version
uvx plexosdb-mcp --help

You can also set read-only mode via environment variable:

PLEXOSDB_MCP_READ_ONLY=1 uvx plexosdb-mcp

Pin a specific version in production:

uvx plexosdb-mcp==0.1.0
uvx plexosdb-mcp==0.1.0 --read-only

2a) Local development (repo checkout)

When working from this repository before publishing, use the nested project path so uv installs plexosdb-mcp rather than the root plexosdb package:

uv run --project src/plexosdb-mcp plexosdb-mcp health
uv run --project src/plexosdb-mcp plexosdb-mcp --read-only

If it starts successfully, it will wait for MCP client requests.

2b) One-shot CLI commands (no Node.js required)

All diagnostic subcommands output JSON to stdout and exit. Errors write a structured JSON object to stderr and exit with code 1. This makes them safe to use in pipelines and agent scripts.

Command

Output

plexosdb-mcp health

{"ok": true, "active_sessions": 0, "mode": "cli"}

plexosdb-mcp version

{"ok": true, "version": "…", "plexosdb_version": "…", "python": "…"}

plexosdb-mcp doctor

{"ok": true, "checks": [{…}, …]} — exits 1 if any check fails

plexosdb-mcp capabilities

{"ok": true, "tools": {…}, "subcommands": […]}

All data-bearing commands accept --json for explicit machine-readable output:

uvx plexosdb-mcp health --json
uvx plexosdb-mcp version --json
uvx plexosdb-mcp doctor --json
uvx plexosdb-mcp capabilities --json

CLI contract:

  • Data goes to stdout as compact JSON.

  • Diagnostic messages (TTY warnings) go to stderr.

  • Failures emit {"ok": false, "error": "…"} to stderr and exit with code 1.

  • Usage errors (bad flags) exit with code 2 (argparse default).

  • plexosdb-mcp --version prints the version string and exits 0.

doctor is the recommended pre-flight check for agents before opening a session:

uvx plexosdb-mcp doctor --json && echo "ready"

3) Interact with the server and verify tools

A simple way to test is with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx plexosdb-mcp

npx is only required for Inspector UI testing. It is not required for production use of plexosdb-mcp itself.

In the Inspector UI:

  1. Connect to the server process.

  2. Call health and confirm { "ok": true } is returned.

  3. Call create_empty_session and copy the returned session_id.

  4. Call add_object with:

    • session_id: <your-session-id>

    • class_name: Generator

    • name: Solar_MCP_01

  5. Call list_objects_by_class with:

    • session_id: <your-session-id>

    • class_name: Generator

  6. Confirm Solar_MCP_01 appears in the response.

  7. Call close_session and confirm { "closed": true }.

4) Load a real XML and export a modified one

Typical sequence:

  1. open_xml_session with xml_path set to your source model file.

  2. add_object and optional add_property or add_membership.

  3. save_xml with output_path set to the target file path.

  4. close_session.

5) Configure an MCP client (example)

Most MCP clients support a JSON server entry with command + args. Use this shape:

{
  "mcpServers": {
    "plexosdb": {
      "command": "uvx",
      "args": ["plexosdb-mcp==0.1.0", "--read-only"]
    }
  }
}

Remove --read-only only when you intentionally want write/export tools enabled.

After adding the server entry, reconnect the client and run health.

Notes

  • The MCP server keeps only one active session at a time.

  • Calling create_empty_session or open_xml_session replaces any existing active session and returns a new session_id.

  • Keep the same session_id for all operations in one editing flow.

  • Call close_session when done to release in-memory DB resources.

  • add_property requires that the target property is valid for the class/collection in the current model.