# HOPE-AI: Running HOPE with an LLM Agent

HOPE supports agentic AI control via the Model Context Protocol (MCP) — a standard that lets LLM hosts invoke tools, run models, and read results without any manual scripting. This page explains two supported setups:

• Claude Desktop with a local full-access stdio MCP server for running cases, changing settings, and opening dashboards.
• ChatGPT web with a remote read-only MCP server for inspecting cases and outputs through developer mode.

Available Tools

Once configured, Claude Desktop will have access to 16 HOPE tools organized into six groups:

Job Execution

Settings Management

Output Reading

Scenario Comparison

Audit Tools

Dashboard

Prerequisites

• HOPE cloned and Julia environment instantiated (see Installation)
• Python >= 3.10 (the MCP server is a Python package)
• uv (astral.sh/uv) — fast Python package manager
• Claude Desktop (claude.ai/download) or any MCP-compatible LLM host

One-Time Setup

Step 1 — Install uv

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal after installation so uv is on your PATH.

Step 2 — Sync the MCP server Python package

uv --directory /path/to/HOPE/tools/hope_mcp_server sync

This creates a local .venv inside tools/hope_mcp_server/ with all dependencies (including the mcp package).

Step 2b — Optional agent preflight check

Before the first solver-backed run in a new session, you can verify that Claude is pointing at the correct HOPE Julia environment and that the requested solver can be initialized:

julia --project=/path/to/HOPE /path/to/HOPE/tools/repo_utils/agent_preflight_check.jl \
  ModelCases/MD_GTEP_clean_case

To explicitly test a commercial solver such as Gurobi:

julia --project=/path/to/HOPE /path/to/HOPE/tools/repo_utils/agent_preflight_check.jl \
  ModelCases/MD_GTEP_clean_case --solver gurobi

The script prints a short pass/fail checklist and exits nonzero if the environment, case path, solver package, license handshake, or HOPE.initiate_solver(...) path fails.

Step 3 — Configure Claude Desktop

Locate your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json (typically C:\Users\<user>\AppData\Roaming\Claude\claude_desktop_config.json)
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the hope server entry:

Windows example:

{
  "mcpServers": {
    "hope": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\HOPE\\tools\\hope_mcp_server",
        "run",
        "hope-mcp-server"
      ],
      "env": {
        "HOPE_REPO_ROOT": "C:\\path\\to\\HOPE",
        "HOPE_JULIA_BIN": "C:\\Users\\<user>\\.julia\\juliaup\\julia-1.x.y+0.x64.w64.mingw32\\bin\\julia.exe"
      }
    }
  }
}

macOS / Linux example:

{
  "mcpServers": {
    "hope": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/HOPE/tools/hope_mcp_server",
        "run",
        "hope-mcp-server"
      ],
      "env": {
        "HOPE_REPO_ROOT": "/path/to/HOPE",
        "HOPE_JULIA_BIN": "/path/to/.julia/juliaup/julia-1.x.y+0.aarch64.apple.darwin14/bin/julia"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Step 4 — Optional ChatGPT web read-only setup

ChatGPT currently requires a remote HTTPS MCP endpoint. The simplest workflow is:

1. start the read-only HOPE server locally,
2. expose it through a tunnel such as Cloudflare Tunnel,
3. connect the resulting HTTPS /mcp URL in ChatGPT web developer mode.

The read-only ChatGPT entrypoint exposes only analysis tools such as hope_case_info, hope_output_summary, hope_read_output, and comparison/audit helpers. It does not expose hope_run_hope, hope_update_settings, or dashboard-launch tools.

Step 4a — Start the read-only server locally

Windows (PowerShell):

$env:HOPE_REPO_ROOT = "C:\path\to\HOPE"
$env:HOPE_MCP_PORT = "8001"
$env:HOPE_MCP_HOST = "127.0.0.1"
$env:HOPE_MCP_PUBLIC_HOSTNAME = "hope.example.com"
& "C:\path\to\HOPE\tools\hope_mcp_server\.venv\Scripts\python.exe" -m hope_mcp_server.chatgpt

macOS / Linux:

HOPE_REPO_ROOT=/path/to/HOPE \
HOPE_MCP_PORT=8001 \
HOPE_MCP_HOST=127.0.0.1 \
HOPE_MCP_PUBLIC_HOSTNAME=hope.example.com \
/path/to/HOPE/tools/hope_mcp_server/.venv/bin/python -m hope_mcp_server.chatgpt

Step 4b — Publish the local port through Cloudflare Tunnel

1. Install cloudflared.
2. Create a Cloudflare Tunnel and install the connector on the machine running HOPE.
3. Add a published application route (public hostname), for example:
   • hostname: hope.example.com
   • service: http://localhost:8001
4. Keep the local HOPE server process running while the tunnel is active.

Step 4c — Connect the MCP endpoint in ChatGPT web

Use the tunnel URL with the MCP path:

https://hope.example.com/mcp

If you test that URL with a plain browser or curl, you may see a 406 Not Acceptable response asking for text/event-stream. That is expected: it means the route is reachable, but the client is not speaking MCP yet.

For the full current ChatGPT read-only deployment notes, see:

• tools/hope_mcp_server/README.md

Typical Claude Desktop Session

Julia's first startup includes precompilation which can take several minutes. The recommended flow is:

1. Warm up Julia (once per session)

"Warm up Julia for HOPE."

Claude calls hope_warmup, which launches Julia precompilation in the background and returns a job_id. Claude then polls hope_job_status until precompilation finishes (~3-5 min on first call, much faster on subsequent calls in the same session).

2. Validate and optionally update settings

"Check the mdgtepclean case settings and enable the carbon cap."

Claude calls hope_validate_case to detect any contradictions, then hope_update_settings to patch carbon_policy: 1 into HOPE_model_settings.yml. The original file is backed up automatically.

3. Run a HOPE case

"Run the mdgtepclean HOPE case."

Claude calls hope_run_hope (or hope_run_holistic for a two-stage GTEP-PCM run), which launches HOPE as a background process and returns a job_id immediately. Claude polls hope_job_status until the run completes. When done, the output summary is returned automatically.

4. Inspect results

"Summarize the capacity investments. Are we in compliance with the carbon cap?"

Claude calls hope_output_summary for the cost and build summary, then hope_emission_compliance to check carbon and RPS policy compliance — all instant, reading only the output CSVs.

5. Drill into specifics

"Show me the hourly dispatch for solar in zone MD."

Claude calls hope_read_output with filename="dispatch.csv" and filters={"Zone": "MD", "Technology": "SolarPV"}.

6. Compare scenarios

"How does cost and emissions change if I also enable the RPS target? Run that version and compare."

Claude calls hope_update_settings to enable clean_energy_policy: 1, re-runs with hope_run_hope, then calls hope_compare_cases to get a side-by-side diff of cost, capacity, and CO2.

Supported Cases

The MCP server now discovers cases dynamically from ModelCases/ by looking for case directories that contain:

Settings/HOPE_model_settings.yml

Accepted case identifiers include:

• exact ModelCases directory names such as USA_64zone_GTEP_case
• prefixed paths such as ModelCases/USA_64zone_GTEP_case
• the legacy alias md_gtep_clean

No manual case registry update is needed when you add a new valid case folder under ModelCases/.

Example Prompts

The prompts below demonstrate what you can ask Claude in a typical session. Copy them verbatim or adapt them to your case.

Job Execution

hope_warmup — Pre-compile Julia before the first run

"Warm up Julia for HOPE." "Initialize the HOPE Julia environment and let me know when it's ready." "Pre-compile HOPE so the first model run starts fast."

hope_run_hope — Launch a single-case HOPE optimization

"Run the md_gtep_clean HOPE case." "Start a HOPE GTEP run for the Maryland clean energy case." "Launch a HOPE model run and tell me when it finishes."

hope_run_holistic — Two-stage GTEP→PCM workflow

"Run the holistic two-stage analysis: first solve capacity expansion, then re-run production cost with the built fleet fixed." "Execute a holistic HOPE run for the md_gtep_clean case using the md_pcm_clean case for the PCM stage."

hope_run_erec — EREC reliability postprocessing

"Run EREC on the completed md_gtep_clean run to compute each resource's reliability contribution." "After the GTEP run finishes, quantify how much capacity credit each new solar and wind plant earns."

hope_job_status — Poll a background job

"What's the status of job a3f8c21b?" "Is the HOPE run still going? Give me the latest output." "Check whether the warmup job has finished."

Settings Management

hope_update_settings — Patch model settings

"Enable the carbon cap in the md_gtep_clean case." "Switch the solver to HiGHS for the Maryland case." "Turn on unit commitment and nodal network modeling." "Set the carbon price to $50/ton in md_gtep_clean." "Disable the RPS target and enable the clean energy standard instead." "Enable shadow price output and make sure the network model is set to nodal."

hope_validate_case — Check for contradictions before running

"Validate the md_gtep_clean case settings before I run it." "Check whether there are any contradictions or missing files in this case." "Is this case configured correctly to produce nodal prices?"

Output Reading

hope_case_info — Inspect settings and output file inventory

"What settings is the md_gtep_clean case using?" "List all the output files from the last HOPE run."

hope_output_summary — Summarize cost and capacity results

"Summarize the results from the md_gtep_clean run." "What are the total system costs, new capacity builds, and storage investments?" "Give me a high-level overview of the capacity expansion results."

hope_read_output — Read any specific output CSV

"Show me the dispatch for solar PV in zone MD." "Read the capacity.csv output and filter for wind technologies." "What does the transmission_flows.csv file look like for the first 24 hours?" "Show me storage charge/discharge for the BESS resources in zone PJM."

hope_emission_compliance — Check carbon and RPS compliance

"Are we in compliance with the carbon cap? How close are we to the limit?" "Summarize per-state carbon and RPS compliance from the latest run." "Did any state violate its RPS target? What are the penalty costs?"

hope_nodal_prices — Read locational marginal prices

"What are the average nodal prices across all buses?" "Show me the LMPs for buses in zone MD for hours 1–48." "Which bus had the highest LMP during the peak demand period?"

Scenario Comparison

hope_compare_cases — Side-by-side scenario comparison

"Compare costs and emissions between the baseline and the carbon cap cases." "How does capacity investment change if I enable the RPS target? Run that version and compare." "Show me a side-by-side table of capacity builds, system cost, and CO2 across the three Maryland scenarios." "What's the cost difference between the nodal and zonal network models?"

Audit Tools

hope_rep_day_audit — Representative period summary

"Summarize the representative-day clustering for the md_gtep_clean case." "How many representative periods are used, and what's the compression ratio versus a full year?" "Which weeks are mapped to each representative day?"

hope_aggregation_audit — Resource aggregation summary

"How many generator clusters were created from the raw resource data?" "Summarize the resource aggregation: how many generators were grouped into how many clusters?" "Show me the per-cluster capacity for the wind aggregation."

Dashboard

hope_open_dashboard / hope_close_dashboard — Local interactive dashboard

"Open the dashboard for the md_gtep_clean case." "Launch the GTEP dashboard so I can explore capacity builds interactively." "Close the dashboard when I'm done." "Stop all running dashboards."

Troubleshooting

MCP server does not appear in Claude Desktop Verify the config JSON is valid (no trailing commas, no syntax errors). Restart Claude Desktop fully (quit and reopen).

uv command not found Restart your terminal after installing uv, or manually add ~/.local/bin (macOS/Linux) or %USERPROFILE%\.local\bin (Windows) to your PATH.

Julia warmup job keeps running for a long time This is expected on the very first call — Julia downloads and compiles ~130 packages. Subsequent warmups in the same session are instant since the cache is warm.

hope_warmup fails with AppLocker / Application Control blocking a DLL Set JULIA_DEPOT_PATH in Claude Desktop's config to a directory that your Windows policy explicitly trusts, then restart Claude Desktop and run hope_warmup again. On managed Windows machines, moving the depot outside C:\Users can help, but it is not sufficient by itself: a path like E:\julia_depot may still be blocked unless your IT policy allows that location or whitelists the blocked Julia artifact DLL (for example libmetis_*.dll).

hope_run_hope fails with hope_environment_not_instantiated Call hope_warmup first and wait for it to complete before calling hope_run_hope.

hope_run_erec fails with snapshot_not_found Set save_postprocess_snapshot: 1 in HOPE_model_settings.yml (use hope_update_settings) and re-run the case before calling hope_run_erec.

hope_nodal_prices returns price_file_not_found LMP output requires network_model > 0 and write_shadow_prices: 1 in settings. Use hope_update_settings to enable both, then re-run.

Job ID not found Job IDs are in-memory and only valid for the current MCP server session. If Claude Desktop was restarted, old job IDs are gone — start a new warmup/run.

Further Resources

• PowerAgent community
• PowerMCP repository — MCP servers for HOPE, PyPSA, OpenDSS, PowerWorld, and more
• Model Context Protocol docs
• PowerMCP Tutorial PDF