Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Grid Data Models MCP Server

MCP (Model Context Protocol) server integration for grid-data-models.

Overview

This package provides an MCP server that exposes grid-data-models functionality as tools for AI agents and assistants. It enables validation error fixing, system merging/disaggregation, inspection, and utility operations on distribution power system models. The server also provides documentation search and API reference capabilities to help answer questions about the grid-data-models library itself.

Features

Installation

pip install grid-data-models

For development:

git clone https://github.com/NLR-Distribution-Suite/grid-data-models.git
cd grid-data-models
pip install -e ".[dev]"

Quick Start

Using with VS Code GitHub Copilot Agent Mode

GitHub Copilot in VS Code supports MCP servers through Agent Mode. Follow these steps to set up the server:

1. Install the package

pip install grid-data-models

Verify the server command is available:

which gdm-mcp-server

Note: If you’re using conda or a virtual environment, note the full path to the executable (e.g., /opt/homebrew/Caskroom/miniconda/base/envs/gdm/bin/gdm-mcp-server). VS Code may not activate your environment, so using the full path is recommended.

2. Create the MCP configuration file

Create a .vscode/mcp.json file in your workspace root:

{
  "servers": {
    "gridDataModels": {
      "type": "stdio",
      "command": "gdm-mcp-server",
      "env": {
        "GDM_REPO_PATH": "/path/to/grid-data-models"
      }
    }
  }
}

Tip: If VS Code can’t find the command, replace "gdm-mcp-server" with the full path to the executable.

Set GDM_REPO_PATH to the local clone of the grid-data-models repository (used for documentation search).

3. Start the server

Alternatively, you should see Start code lenses directly in the mcp.json file.

4. Use tools in Copilot Chat

  1. Open Copilot Chat (Cmd+Shift+I / Ctrl+Shift+I)

  2. Switch to Agent mode using the dropdown at the top of the chat panel

  3. Click the Tools icon (wrench) in the chat input area to verify the server’s 22 tools are listed and enabled

  4. Ask questions naturally — the agent automatically selects the right tools:

    • “Get a summary of the system in /path/to/model.json”

    • “Diagnose validation errors in system.json and suggest fixes”

    • “What fields does DistributionBus have?”

    • “Show me code examples for working with time series”

  5. To reference a specific tool, type # followed by the tool name (e.g., #get_system_summary)

See Using Grid Data Models MCP Server with VS Code for more detailed examples.

Using with Claude Desktop

MCP servers are also supported in Claude Desktop. Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop and the assistant will have access to all 22 GDM tools.

Starting the MCP Server Standalone

Run the server directly:

gdm-mcp-server

Or with custom host/port:

gdm-mcp-server --host localhost --port 8000

Using with Other MCP Clients

Any MCP-compatible client can connect to the server. The server exposes 22 tools for working with distribution power system models.

Runtime Tool Toggle

The server supports runtime enable/disable for non-control tool calls. This is useful when you want a UI switch (or policy gate) without restarting the server.

Example payloads:

{"enabled": false}
{"enabled": true}

You can also set the startup default from CLI:

gdm-mcp-server --tool-calls-disabled
gdm-mcp-server --tool-calls-enabled

model_ref Interoperability

Path-based tools now support either legacy system_path or a model_ref object, enabling compatibility with persisted model registries.

model_ref shape

{
  "model_id": "abc123def456",
  "version": 2
}

Direct path-carrying references are also valid:

{
  "stored_path": "/abs/path/to/system.json"
}

Resolution behavior

Resolution order:

  1. stored_path

  2. path

  3. source_path

  4. Registry lookup by model_id / version

Registry lookup uses:

Backward compatibility

Existing clients using system_path continue to work unchanged.

Example payloads

Legacy:

{
  "system_path": "/abs/path/to/system.json"
}

Registry-backed:

{
  "model_ref": {
    "model_id": "abc123def456",
    "version": 2
  }
}

Available Tools

Validation (3 tools)

System Operations (3 tools)

Inspection (7 tools)

Utilities (2 tools)

Documentation / Knowledge (5 tools)

Server Control (2 tools)

Example Usage

Validating and Fixing a System

# Through MCP client (e.g., Claude or Copilot)
"Diagnose the system in model.json and apply automatic fixes"

Merging Systems

# Through MCP client
"Merge system1.json and system2.json into combined_system.json"

Splitting by Feeder

# Through MCP client
"Split the system in large_model.json into separate systems for each feeder"

Getting Documentation and API Information

# Through MCP client
"How do I create a DistributionBus?"
"Show me code examples for working with time series"
"What fields does DistributionLoad have?"

Compatibility

Development

Run tests:

pytest tests/

Run linting:

ruff check src/

License

BSD 3-Clause License. See LICENSE.txt for details.

Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

Support

For issues and questions:

Citation

If you use this software in your research, please cite:

@software{grid_data_models_mcp,
  title = {Grid Data Models MCP Server},
  author = {Latif, Aadil and Duwadi, Kapil},
  year = {2026},
  organization = {National Renewable Energy Laboratory}
}
On CIM and GDM
Model Representation
MCP Server
Using Grid Data Models MCP Server with VS Code