{ "markdown": "# gpu-mcp-server\n\n[![CI](https://github.com/pmady/gpu-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/pmady/gpu-mcp-server/actions/workflows/ci.yml)\n[![Helm](https://github.com/pmady/gpu-mcp-server/actions/workflows/helm.yaml/badge.svg)](https://github.com/pmady/gpu-mcp-server/actions/workflows/helm.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/pmady/gpu-mcp-server)](https://goreportcard.com/report/github.com/pmady/gpu-mcp-server)\n[![Go Reference](https://pkg.go.dev/badge/github.com/pmady/gpu-mcp-server.svg)](https://pkg.go.dev/github.com/pmady/gpu-mcp-server)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/pmady/gpu-mcp-server/badge)](https://securityscorecards.dev/viewer/?uri=github.com/pmady/gpu-mcp-server)\n[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF_Best_Practices-in_progress-yellow)](https://www.bestpractices.dev/en)\n\n> **Note:** the OpenSSF Best Practices questionnaire is in progress. Once the\n> project entry is registered at , swap the\n> static badge above for the live one:\n> `[![OpenSSF Best Practices](https://www.bestpractices.dev/projects//badge)](https://www.bestpractices.dev/projects/)`\n\nAn [MCP](https://modelcontextprotocol.io/) server that exposes NVIDIA GPU metrics as tools.\nAny MCP-compatible AI agent (Claude, Goose, Cursor, etc.) can query real-time GPU\nutilization, memory, temperature, power, PCIe and NVLink throughput no Prometheus\nor dcgm-exporter required.\n\nBuilt on the [official Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk)\nand [NVIDIA go-nvml](https://github.com/NVIDIA/go-nvml).\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_gpus` | List all GPUs with utilization and memory info |\n| `get_gpu_metrics` | Detailed metrics for a GPU by index or UUID |\n| `get_gpu_processes` | PID-level GPU process attribution |\n| `gpu_summary` | Aggregate stats across all devices |\n\nAll tools support MIG (Multi-Instance GPU) - MIG instances appear as separate\ndevices with their parent GPU's shared metrics (temperature, power, PCIe).\n\n## Sample output\n\nEach tool returns structured JSON. The examples below show the shape of the\ndata an agent receives from a node with two NVIDIA A100 GPUs.\n\n`list_gpus`:\n\n```json\n{\n \"count\": 2,\n \"devices\": [\n {\n \"index\": 0,\n \"uuid\": \"GPU-aaaa-1111\",\n \"name\": \"NVIDIA A100-SXM4-80GB\",\n \"gpu_utilization_percent\": 85,\n \"memory_used_mib\": 57344,\n \"memory_total_mib\": 81920\n },\n {\n \"index\": 1,\n \"uuid\": \"GPU-bbbb-2222\",\n \"name\": \"NVIDIA A100-SXM4-80GB\",\n \"gpu_utilization_percent\": 20,\n \"memory_used_mib\": 12288,\n \"memory_total_mib\": 81920\n }\n ]\n}\n```\n\n`get_gpu_metrics` (with `{\"index\": 0}` or `{\"uuid\": \"GPU-aaaa-1111\"}`):\n\n```json\n{\n \"index\": 0,\n \"uuid\": \"GPU-aaaa-1111\",\n \"name\": \"NVIDIA A100-SXM4-80GB\",\n \"gpu_utilization_percent\": 85,\n \"memory_utilization_percent\": 70,\n \"memory_used_mib\": 57344,\n \"memory_total_mib\": 81920,\n \"temperature_celsius\": 72,\n \"power_draw_watts\": 300,\n \"power_limit_watts\": 400,\n \"pcie_tx_kbps\": 0,\n \"pcie_rx_kbps\": 0,\n \"nvlink_tx_mbps\": 0,\n \"nvlink_rx_mbps\": 0\n}\n```\n\n`gpu_summary`:\n\n```json\n{\n \"device_count\": 2,\n \"avg_gpu_utilization\": 52.5,\n \"avg_memory_utilization\": 42.5,\n \"total_memory_used_mib\": 69632,\n \"total_memory_total_mib\": 163840,\n \"max_temperature_celsius\": 72,\n \"total_power_draw_watts\": 375\n}\n```\n\nMIG instances add `is_mig`, `parent_gpu`, and `mig_profile` fields to the\n`get_gpu_metrics` and `list_gpus` payloads.\n\n## Quick start\n\n```bash\n# build (requires CGO + NVML headers on Linux)\nmake build\n\n# run the server communicates over stdio\n./gpu-mcp-server\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"gpu\": {\n \"command\": \"/path/to/gpu-mcp-server\"\n }\n }\n}\n```\n\n### Goose\n\n```yaml\nextensions:\n gpu-metrics:\n type: stdio\n cmd: /path/to/gpu-mcp-server\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` for a project, or `~/.cursor/mcp.json` for all\nprojects:\n\n```json\n{\n \"mcpServers\": {\n \"gpu\": {\n \"type\": \"stdio\",\n \"command\": \"/path/to/gpu-mcp-server\"\n }\n }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"gpu\": {\n \"command\": \"/path/to/gpu-mcp-server\"\n }\n }\n}\n```\n\n## Build\n\nRequires Go 1.23+, CGO, and NVIDIA drivers on the target machine.\n\n```bash\nmake build # compile binary\nmake test # run tests (no GPU needed uses mock)\nmake lint # golangci-lint\nmake docker # container image\n```\n\nTests use a mock collector, so they run anywhere no GPU hardware required.\n\n## Docker\n\nPrebuilt multi-arch images (linux/amd64, linux/arm64) are published to GHCR on every release.\n\n```bash\ndocker pull ghcr.io/pmady/gpu-mcp-server:latest\ndocker run --rm -i --gpus all ghcr.io/pmady/gpu-mcp-server:latest\n```\n\nThe host needs the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-container-toolkit)\ninstalled for `--gpus all` to work. The server speaks MCP over stdio, so the\n`-i` flag is required — don't drop it.\n\n```json\n{\n \"mcpServers\": {\n \"gpu\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"--gpus\", \"all\", \"ghcr.io/pmady/gpu-mcp-server:latest\"]\n }\n }\n}\n```\n\nPin a specific version via tag instead of `:latest`, e.g. `ghcr.io/pmady/gpu-mcp-server:v0.1.0`.\n\n## Architecture\n\n```\nAgent (Claude/Goose) ─── MCP (stdio) ──→ gpu-mcp-server ──→ NVML ──→ GPU\n │\n Tools:\n • list_gpus\n • get_gpu_metrics\n • gpu_summary\n```\n\nThe server runs as a local process alongside the agent. It calls NVML directly\nthrough cgo — no sidecar, no network hops, no metric pipeline to configure.\n\n## Project info\n\n- **License:** Apache 2.0\n- **Language:** Go\n- **AAIF project alignment:** [MCP](https://modelcontextprotocol.io/)\n- **Related:** [keda-gpu-scaler](https://github.com/pmady/keda-gpu-scaler) (GPU autoscaling for Kubernetes)\n- **Whitepaper:** [GPU-Aware Autoscaling in Cloud Native AI Infrastructure](https://github.com/pmady/keda-gpu-scaler/blob/main/docs/cncf-tag-infra/gpu-aware-autoscaling-whitepaper.md) — CNCF TAG Infrastructure initiative ([TOC #2188](https://github.com/cncf/toc/issues/2188))\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for the 12-month public roadmap.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for how to get involved.\n\n## Contributors\n\nThanks to all our [contributors](CONTRIBUTORS.md)! Add yourself via PR.\n\n## Governance\n\nThis project follows [Linux Foundation Minimum Viable Governance](GOVERNANCE.md).\n\n## Documentation\n\n- [Full documentation](https://gpu-mcp-server.readthedocs.io) - hosted on Read the Docs\n- [ROADMAP.md](ROADMAP.md) - public roadmap\n- [GOVERNANCE.md](GOVERNANCE.md) - decision-making process\n- [DEPENDENCIES.md](DEPENDENCIES.md) - external dependencies and licenses\n- [SECURITY.md](SECURITY.md) - vulnerability reporting\n- [AGENTS.md](AGENTS.md) - instructions for AI agents working on this repo\n- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - community standards\n\n## Star History\n\n\n \n \n \n \"Star\n \n\n", "bytes": 7945, "sha": "85f92159f0aca1a7553169267838fc2e0bce55e6eb1a8d9426353881519a1c53", "repo_slug": "pmady/gpu-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_pmady_gpu_mcp_server_13bb9735/readme" }