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
Section titled “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
Section titled “1) Install dependencies”Install the package you need:
- Core library only:
uv add plexosdb- MCP server package (includes MCP CLI entrypoint):
uv add plexosdb-mcpFor local development from this repository:
uv sync --all-groups2) Start the MCP server
Section titled “2) Start the MCP server”Happy path — run from a published package using uvx:
uvx plexosdb-mcpSafe path — read-only mode (recommended for untrusted prompts/hosts):
uvx plexosdb-mcp --read-onlySmoke checks — verify the server is reachable without starting the MCP daemon:
uvx plexosdb-mcp healthuvx plexosdb-mcp --versionuvx plexosdb-mcp --helpYou can also set read-only mode via environment variable:
PLEXOSDB_MCP_READ_ONLY=1 uvx plexosdb-mcpPin a specific version in production:
uvx plexosdb-mcp==0.1.0uvx plexosdb-mcp==0.1.0 --read-only2a) Local development (repo checkout)
Section titled “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 healthuv run --project src/plexosdb-mcp plexosdb-mcp --read-onlyIf it starts successfully, it will wait for MCP client requests.
2b) One-shot CLI commands (no Node.js required)
Section titled “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 --jsonuvx plexosdb-mcp version --jsonuvx plexosdb-mcp doctor --jsonuvx plexosdb-mcp capabilities --jsonCLI 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 --versionprints 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
Section titled “3) Interact with the server and verify tools”A simple way to test is with the MCP Inspector:
npx @modelcontextprotocol/inspector uvx plexosdb-mcpnpx is only required for Inspector UI testing. It is not required for
production use of plexosdb-mcp itself.
In the Inspector UI:
- Connect to the server process.
- Call
healthand confirm{ "ok": true }is returned. - Call
create_empty_sessionand copy the returnedsession_id. - Call
add_objectwith:session_id:<your-session-id>class_name:Generatorname:Solar_MCP_01
- Call
list_objects_by_classwith:session_id:<your-session-id>class_name:Generator
- Confirm
Solar_MCP_01appears in the response. - Call
close_sessionand confirm{ "closed": true }.
4) Load a real XML and export a modified one
Section titled “4) Load a real XML and export a modified one”Typical sequence:
open_xml_sessionwithxml_pathset to your source model file.add_objectand optionaladd_propertyoradd_membership.save_xmlwithoutput_pathset to the target file path.close_session.
5) Configure an MCP client (example)
Section titled “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.
- The MCP server keeps only one active session at a time.
- Calling
create_empty_sessionoropen_xml_sessionreplaces any existing active session and returns a newsession_id. - Keep the same
session_idfor all operations in one editing flow. - Call
close_sessionwhen done to release in-memory DB resources. add_propertyrequires that the target property is valid for the class/collection in the current model.