HPC

This MCP server provides tooling to run and integrate HPC-focused MCP capabilities with large language models. It enables you to launch a local MCP server that can be managed by IDEs and editors, making it easier to test debugging and tooling workflows with your HPC applications.

How to use

You interact with the HPC MCP Server through your editor or IDE by running the MCP server locally and then connecting your editor’s MCP client to it. The server is designed to be run as a local, stdio-based process so your editor can communicate over standard input and output.

To configure a client, you can add a server entry that points to a local UV-based command that launches the MCP server. The following configuration demonstrates how to register the server in a Cursor setup and in Zed, with an example path placeholder you should replace with your actual project path.

{
  "mcpServers": {
    "hpc_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to>hpc-mcp",
        "run",
        "src/debug.py"
      ]
    }
  }
}

How to install

Prerequisites: ensure you have a compatible runtime and dependency manager installed. This server uses Python and the uv tool for dependency management and running tasks.

Install uv if you do not have it yet. Then install dependencies and run tests using the following command.

uv run --dev pytest

Additional setup for editors

Cursor, VSCode, and Zed can all connect to a local MCP server. Use the configurations shown below to add a server entry in each editor.

Cursor configuration (example) shows adding a custom MCP server that starts the server from a local path.

{
  "mcpServers": {
    "hpc-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to>/hpc-mcp",
        "run",
        "src/debug.py"
      ]
    }
  }
}

Zed editor setup

In Zed you add a server under the Model Context Protocol (MCP) Servers section to enable local MCP execution.

Example configuration for Zed uses the same structure as Cursor but includes an environment block for completeness.

{
  // The name of your MCP server
  "hpc-mcp": {
    // The command which runs the MCP server
    "command": "uv",
    // The arguments to pass to the MCP server
    "args": [
      "--directory",
      "<path/to>/hpc-mcp",
      "run",
      "src/debug.py"
    ],
    // The environment variables to set
    "env": {}
  }
}

Test the MCP Server

Test the MCP using a simple example. Build the example, then probe the LLM agent with a request to debug a crash in a small program.

cd example/simple
make

Running local LLMs with Ollama

To run the hpc-mcp tool with a local Ollama model, use the Zed editor so it detects local Ollama models automatically. Ensure the hpc-mcp server is installed and available in Zed.

Note: Not all models support calling MCP tools. Some configurations may work with models like qwen3:latest.

Core dependencies

The server depends on Python, uv, and fastmcp to operate effectively.

Available tools

debug_crash

A focused MCP tool to diagnose and debug a crashing executable by instrumenting the run and collecting diagnostic output.