# netboxlabs/netbox-mcp-server architecture

> Architecture diagram of the GitHub repository netboxlabs/netbox-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netboxlabs/netbox-mcp-server
- Repository: https://github.com/netboxlabs/netbox-mcp-server

## Overview

##### Project type and purpose
- This is an open-source, single‐service “middleware” application implementing a read-only Model Context Protocol (MCP) server for NetBox.
- It exposes a small set of “tools” (get_objects, get_object_by_id, get_changelogs) over MCP so LLM clients can query NetBox data.

##### File structure
- Top-level service entrypoint: server.py
- NetBox API client logic: netbox_client.py
- Dependency and build manifests: requirements.txt, pyproject.toml
- Repository metadata and contribution templates under .github/
- No frontend/UI components—pure backend microservice

##### README for insights
- Describes three MCP tools and required environment variables (NETBOX_URL, NETBOX_TOKEN)
- Usage pattern: external LLM client invokes the MCP server via command (`uv run server.py`)
- Underlying flow: MCP server → NetBox REST API

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "External Systems"
        LLM["External LLM Client"]:::external
        NBAPI["NetBox API"]:::external
    end

    subgraph "MCP Server"
        SRV["server.py\n(Entrypoint)"]:::service
        HND["MCP Protocol Handler"]:::service
        DSP["Tool Dispatcher"]:::service
        NBC["netbox_client.py"]:::service
    end

    subgraph "Configuration & Metadata"
        ENV["Environment Variables\n(NETBOX_URL, NETBOX_TOKEN)"]:::config
        REQ["requirements.txt"]:::config
        PY["pyproject.toml"]:::config
        GH[".github/"]:::config
        RMD["README.md"]:::config
        SEC["SECURITY.md"]:::config
    end

    LLM -->|"MCP Request"| SRV
    SRV --> HND
    HND --> DSP
    DSP --> NBC
    NBC -->|"HTTP/REST"| NBAPI
    NBAPI -->|"JSON Data"| NBC
    NBC --> DSP
    DSP --> HND
    HND --> SRV
    SRV -->|"MCP Response"| LLM

    ENV --> SRV
    REQ --> SRV
    PY --> SRV

    classDef external fill:#B3E5FC,stroke:#81D4FA,color:#01579B;
    classDef service fill:#C8E6C9,stroke:#A5D6A7,color:#1B5E20;
    classDef config fill:#ECEFF1,stroke:#CFD8DC,color:#37474F;

    click LLM "https://github.com/netboxlabs/netbox-mcp-server/blob/main/README-client.md"
    click SRV "https://github.com/netboxlabs/netbox-mcp-server/blob/main/server.py"
    click NBC "https://github.com/netboxlabs/netbox-mcp-server/blob/main/netbox_client.py"
    click REQ "https://github.com/netboxlabs/netbox-mcp-server/blob/main/requirements.txt"
    click PY "https://github.com/netboxlabs/netbox-mcp-server/blob/main/pyproject.toml"
    click GH "https://github.com/netboxlabs/netbox-mcp-server/tree/main/.github/"
    click RMD "https://github.com/netboxlabs/netbox-mcp-server/blob/main/README.md"
    click SEC "https://github.com/netboxlabs/netbox-mcp-server/blob/main/SECURITY.md"
```
