Netris Server

Use natural language to manage your Netris network fabric.

---

What it does

The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. This server implements MCP for Netris, a network automation platform that manages physical and virtual network infrastructure. Once connected, you can ask Claude (or any MCP-compatible client) to list sites, create VPCs, configure BGP sessions, set up load balancers, manage NAT rules, and more — all in plain English, without logging into the Netris web UI or writing API calls yourself.

The server exposes 72 tools across 12 modules covering the Netris API surface: VPCs, VPC peering, virtual networks (VNets), eBGP sessions, BGP policy objects, sites, device inventory, IPAM (subnets and allocations), NAT rules, L4 load balancers, ACLs, static routes, and tenants. It also provides 10 workflow guides (MCP prompts) that walk Claude through multi-step operations — from bootstrapping a new deployment and GPU cluster provisioning to VPC peering, ACL setup, and network troubleshooting.

---

Requirements

• Python 3.10 or later
• uv package manager
• A running Netris controller (self-hosted or cloud) with valid credentials

---

Installation

git clone <repo-url>
cd netris-mcp
uv sync

---

Configuration

Environment variables

Copy the example file and fill in your values:

cp .env.example .env

Edit .env:

NETRIS_HOST=netris.example.com
NETRIS_USERNAME=admin
NETRIS_PASSWORD=your-password-here

The full set of environment variables is:

Variable	Required	Default	Description
NETRIS_HOST	Yes	—	Hostname or IP of the Netris controller. No scheme — e.g. netris.example.com, not https://....
NETRIS_USERNAME	Yes	—	Netris login username.
NETRIS_PASSWORD	Yes	—	Netris login password.
NETRIS_SSL_VERIFY	No	true	Set to false or 0 to disable TLS certificate verification. Only do this in trusted lab environments.
NETRIS_SESSION_REFRESH	No	1800	How often (in seconds) the server pings the Netris API to keep the session alive. Minimum 60.
NETRIS_TIMEOUT	No	30.0	Per-request HTTP timeout in seconds.

Variables can be set in a .env file in the project root, or passed directly in the environment (e.g. via the Claude Desktop config below).

---

Connecting to Claude Desktop

Add the following to your Claude Desktop configuration file. On macOS, the file is at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "netris": {
      "command": "uv",
      "args": ["--directory", "/path/to/netris-mcp", "run", "netris-mcp"],
      "env": {
        "NETRIS_HOST": "your-netris-controller.example.com",
        "NETRIS_USERNAME": "admin",
        "NETRIS_PASSWORD": "your-password"
      }
    }
  }
}

Replace /path/to/netris-mcp with the absolute path to where you cloned this repository. Restart Claude Desktop after editing the config. A ready-to-copy example is also available at examples/claude_desktop_config.json.

---

Available Tools

VPC (tools/vpc.py)

Tool	Description
list_vpcs	List all VPCs in Netris.
get_vpc	Get a single VPC by ID.
create_vpc	Create a new VPC, assigning it to a named tenant.
delete_vpc	Delete a VPC by ID.
set_default_vpc	Mark a VPC as the default VPC for the deployment.

VNet (tools/vnet.py)

Tool	Description
list_vnets	List all virtual networks (VNets) in Netris.
get_vnet	Get a single VNet by ID.
create_vnet	Create a new VNet, associating it with one or more sites and a tenant. Optionally assigns a VLAN ID.
delete_vnet	Delete a VNet by ID.

BGP (tools/bgp.py)

Tool	Description
list_bgp_sessions	List all eBGP peer sessions in Netris.
get_bgp_session	Get a single eBGP session by ID.
create_bgp_session	Create an eBGP session with neighbor AS, IPs, optional password/BFD/multihop.
delete_bgp_session	Delete an eBGP session by ID.
list_bgp_objects	List all BGP objects (prefix lists, community lists).
create_bgp_object	Create a BGP prefix list or community list for route filtering.
delete_bgp_object	Delete a BGP object by ID.
list_route_maps	List all route maps for BGP policy.
create_route_map	Create a route map with permit/deny rules for BGP policy.
delete_route_map	Delete a route map by ID.

Sites (tools/sites.py)

Tool	Description
list_sites	List all sites in Netris.
get_site	Get a single site by ID.
create_site	Create a site with name, public ASN, and optional ROH/VM ASNs and site mesh.
update_site	Update a site's name, ASN, or mesh topology.
delete_site	Delete a site by ID.

Inventory (tools/inventory.py)

Tool	Description
list_inventory	List all hardware inventory (switches, SoftGates, controllers).
get_inventory_item	Get a single inventory item by ID.
list_controllers	List all Netris controller nodes.
list_softgates	List all SoftGate nodes.
get_softgate	Get a single SoftGate by ID.
create_softgate	Register a new SoftGate at a site with main and management IPs.
update_softgate	Update a SoftGate's IP configuration.
delete_softgate	Remove a SoftGate from inventory.
list_switches	List all switches managed by Netris.
get_switch	Get a single switch by ID.

IPAM (tools/ipam.py)

Tool	Description
list_subnets	List all subnets in the Netris IPAM (/api/v2/ipam/subnet/).
get_subnet	Get a single subnet by ID.
create_subnet	Create a subnet with prefix, tenant, purpose (common/loopback/management/load-balancer/nat/inactive), and optional site.
update_subnet	Update a subnet's purpose or site assignments.
delete_subnet	Delete a subnet by ID.
list_allocations	List all top-level IP allocations.
get_allocation	Get a single allocation by ID.
create_allocation	Create a new top-level IP allocation block.
delete_allocation	Delete an allocation by ID.

NAT (tools/nat.py)

Tool	Description
list_nat_rules	List all NAT rules (SNAT and DNAT).
get_nat_rule	Get a single NAT rule by ID.
create_snat_rule	Create a Source NAT rule — rewrites source IP of outbound packets. Requires snat_to_ip.
create_dnat_rule	Create a Destination NAT rule — port-forwards inbound traffic to an internal host.
update_nat_rule	Enable or disable a NAT rule.
delete_nat_rule	Delete a NAT rule by ID.

L4 Load Balancer (tools/l4lb.py)

Tool	Description
list_l4lb	List all L4 load balancers.
get_l4lb	Get a single L4LB by ID.
create_l4lb	Create an L4LB with frontend VIP/port, protocol, and backend pool.
update_l4lb_backends	Replace the backend pool of an existing L4LB.
delete_l4lb	Delete an L4LB by ID.

Tenants (tools/tenants.py)

Tool	Description
list_tenants	List all tenants.
get_tenant	Get a single tenant by ID.
create_tenant	Create a tenant with subnet/VNet quotas.
update_tenant	Update a tenant's name or description.
delete_tenant	Delete a tenant (requires all owned resources removed first).

VPC Peering (tools/vpc_peering.py)

Tool	Description
list_vpc_peerings	List all VPC peering connections.
get_vpc_peering	Get a single VPC peering by ID.
create_vpc_peering	Peer two VPCs to enable cross-VPC routing. Most commonly used to peer a tenant VPC with the System VPC for internet access.
delete_vpc_peering	Delete a VPC peering by ID.

Static Routes (tools/static_routes.py)

Tool	Description
list_static_routes	List all static routes across all VPCs.
get_static_route	Get a single static route by ID.
create_static_route	Create a static route with destination prefix, next-hop, VPC, and site.
delete_static_route	Delete a static route by ID.

ACL (tools/acl.py)

Tool	Description
list_acls	List all ACL rules in Netris.
get_acl	Get a single ACL rule by ID.
create_acl	Create an ACL permit/deny rule with source/destination CIDR, optional protocol and port matching.
delete_acl	Delete an ACL rule by ID.

---

Available Guides (Prompts)

MCP prompts are workflow guides that instruct Claude on the correct sequence of steps and tools to use for multi-step operations. Invoke them by name in Claude Desktop (e.g. "Use the site onboarding guide for site DC-West with ASN 65001").

Guide	Parameters	What it does
onboard_new_site	site_name, asn, location (optional)	Walks through creating a site, verifying it, checking controllers, and registering SoftGates.
provision_vpc	vpc_name, tenant, subnet_prefix (optional), site (optional)	Guides through creating a VPC, IP allocation, subnet, and VNet in the correct order.
setup_bgp_peering	peer_name, neighbor_as, neighbor_address, local_address, site	Steps through verifying prerequisites, checking existing sessions, and creating an eBGP session with optional route policy.
setup_load_balancer	lb_name, site, tenant, frontend_ip, frontend_port, protocol (default tcp)	Covers prerequisite checks, backend preparation, L4LB creation, and health status verification.
bootstrap_network	org_name, first_site_name, site_asn, mgmt_prefix, loopback_prefix, public_prefix	End-to-end first-time setup: tenant → site → IP allocations → subnets → SoftGate → VPC → VNet → BGP peering, with a final verification checklist.

---

Example usage

List all sites

"What sites do I have in Netris?"

Claude calls list_sites and presents the results in a readable table.

Provision a VPC

"I need a new VPC called 'prod-vpc' for the 'acme' tenant using subnet 10.100.0.0/24 at site DC-East. Use the VPC provisioning guide."

Claude invokes the provision_vpc guide, then calls list_tenants (verify tenant), create_vpc, create_allocation, create_subnet, and create_vnet in order.

Set up BGP peering

"Configure BGP peering with our upstream ISP at 198.51.100.1 (AS 64512). Our local address is 198.51.100.2 and the site is DC-West."

Claude calls list_sites to verify the site, list_bgp_sessions to check for conflicts, then create_bgp_session.

Set up a load balancer

"Create an L4 load balancer called 'api-lb' on site DC-East for tenant acme. Frontend is 203.0.113.10:443 TCP with backends 10.0.1.10:8443 and 10.0.1.11:8443."

Claude calls list_sites, list_tenants, list_l4lb (conflict check), then create_l4lb.

Bootstrap a new deployment

"Bootstrap a fresh Netris deployment for organisation 'AcmeCorp'. First site is 'HQ' with ASN 65000. Use management block 10.0.0.0/24, loopback 10.0.255.0/29, public 203.0.113.0/26."

Claude invokes the bootstrap_network guide and executes all 7 phases in sequence.

---

Authentication

This server uses Netris's cookie-based session authentication. On startup, it posts your credentials to /api/v2/auth/login and stores the returned connect.sid session cookie in a persistent httpx.AsyncClient. A background task re-hits the /api/v2/auth/profile endpoint every NETRIS_SESSION_REFRESH seconds (default 30 minutes) to prevent the session from expiring during a long-running server process.

Your credentials are read once from the environment at startup and are never transmitted to the AI model or stored outside the running process. They stay on your machine, in your .env file or the Claude Desktop config's env block.

---

Adding new tools

1. Create a new file in src/netris_mcp/tools/, e.g. src/netris_mcp/tools/myresource.py.
2. Import mcp from ..server and define async def functions decorated with @mcp.tool().
3. Use api_url() from ..client to build URLs and get/post/put/delete to make requests.
4. Add an import line at the bottom of src/netris_mcp/server.py:

   from .tools import myresource  # noqa: E402, F401
   

The decorator registers the tool with the MCP server at import time. See the CLAUDE.md file for the exact code pattern and rules to follow.

---

API endpoint verification

URL paths in the tool source files include inline comments linking to the Netris OpenAPI specification at netrisai/swagger-sources for quick cross-referencing. Some resource names differ from the obvious pattern (for example, BGP sessions use /api/v2/ebgp/, and VNets use /api/v2/v-net/). Always verify against the Swagger source when adding new endpoints.

---

License

MIT