Skip to main content
Glama
RyanGallier

netscaler-mcp

by RyanGallier
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

netscaler-mcp

An MCP (Model Context Protocol) server that lets Claude and other MCP clients troubleshoot Citrix NetScaler / ADC appliances over the NITRO REST API, plus a sandboxed SSH path for the per-PPE counters and newnslog events NITRO does not expose.

  • Read-only by default. 52 read and diagnostic tools on the read account (53 with the nsconmsg SSH account), including a generic nitro_get for anything the curated tools do not cover. The 17 admin tools (a generic nitro_write for any configuration change, plus HA failover and sync, enable/disable, drain a service group member, replace a certificate, backup, kill a Gateway or admin session, block and unblock an IP, packet capture, save config, and get_system_file) appear only when you configure an admin account.

  • One NetScaler account per job. Read tools hold only a read-only NITRO account and write tools a separate admin account, so the appliance itself guarantees reads cannot write. Three optional forensic tools (gdb backtrace of a core, search a core's memory, capture the authentication daemon's debug stream) run fixed commands as their own restricted SSH account.

  • HA-aware. Point it at both nodes: HA and crash checks query both, failover finds the current primary, and log and SSH tools take a node argument.

  • Two ways to run it: locally over stdio for one operator, on Linux, Windows or macOS with Node.js 20+, or hosted over HTTP for a team on Azure App Service, with Entra ID sign-in, per-user roles and an audit log of every write.

Tested against NetScaler 13.1 builds 62.23, 64.24 and 64.28, and 14.1 build 73.41 on a standalone appliance. Other 13.1 and 14.1 builds should work. On 14.1, the HA tools (force_ha_failover, force_ha_sync, peer-node reads) have not been tested.

Which mode?

Local (stdio)

Hosted (HTTP)

Who

One operator on their own machine

A team, through one shared endpoint

Runs

As a child process of your MCP client

Azure App Service behind App Service authentication (Easy Auth)

Credentials

Env vars in your MCP client config

Key Vault references in App Service settings

Who may write

Whoever is given the admin account's credentials

Users assigned the NetScaler.Admin Entra app role

Audit

The NetScaler's own audit log

Plus an attempt and result line per admin-tier call (write tools, get_system_file, forensic tools, nitro_write previews), with the user's identity

Appliances

One HA pair, or several with NETSCALER_TARGETS

Several with NETSCALER_TARGETS

Guide

docs/local-mode.md

docs/hosted-mode.md

Related MCP server: network_medic

Quick start (local)

git clone https://github.com/RyanGallier/netscaler-mcp-oss.git && cd netscaler-mcp-oss
npm ci
npm run build

Add it to your MCP client. For Claude Code:

claude mcp add netscaler -e NETSCALER_NSIP=10.0.0.1 -e NETSCALER_USER=mcp_read -e NETSCALER_PASS=changeme -- node /path/to/netscaler-mcp-oss/dist/index.js

Create the read-only NetScaler account first; the built-in read-only policy is not enough. The commands are in docs/local-mode.md.

Or copy .mcp.json.example to .mcp.json and fill it in. Then ask things like "is the HA pair healthy", "why is lb_vs_web DOWN", "which certs expire this quarter" or "trace the nFactor flow for the Gateway login".

Read Security and pin the appliance certificates (how) before pointing it at production.

Configuration

Variable

Required

Default

Purpose

NETSCALER_NSIP

yes, local mode with one appliance

-

NSIP of the primary node (host, or host:port for NITRO on a non-standard port; the SSH tools need a bare host and use NETSCALER_SSH_PORT)

NETSCALER_USER

yes, local mode with one appliance

-

Read-only NITRO account, used by every read tool

NETSCALER_PASS

yes, local mode with one appliance

-

Its password

NETSCALER_ADMIN_USER / NETSCALER_ADMIN_PASS

no

-

Admin NITRO account. Setting it is what turns on the write tools and get_system_file; leave it out of a read-only (helpdesk) config

NETSCALER_PEER_NSIP

no

-

NSIP of the HA peer. Lets the HA tools reach the peer and enables node: peer reads

NETSCALER_PROTOCOL

no

https

https or http

NETSCALER_TIMEOUT

no

15000

NITRO request timeout, ms

NETSCALER_TLS_SHA256

no

-

Comma-separated SHA-256 certificate fingerprints to pin, one per node. Strongly recommended

NETSCALER_SSH_USER / NETSCALER_SSH_PASS

no

-

SSH user for run_nsconmsg. Leave unset to disable that tool

NETSCALER_SSH_PORT

no

22

SSH port

NETSCALER_SSH_TIMEOUT

no

30000

SSH command timeout, ms

NETSCALER_SSH_SHA256

no

-

Comma-separated SSH host key fingerprints to pin (SHA256:...)

NETSCALER_FORENSICS_USER / NETSCALER_FORENSICS_PASS

no

-

Restricted SSH account. Setting it turns on the forensic tools

NETSCALER_BLOCK_PROTECT

no

-

Comma-separated /24s that block_ip_acl refuses, e.g. your own management egress. Applies to every appliance

NETSCALER_TARGETS

no

-

Several appliances: comma-separated short names. Each one reads the appliance settings above (all except NETSCALER_BLOCK_PROTECT) under NS_<NAME>_ instead of NETSCALER_, which are then ignored. Hosted mode always uses it, even for one appliance

Several appliances, either mode: set NETSCALER_TARGETS=east,west and give each one the settings above under its own prefix (NS_EAST_NSIP, NS_EAST_USER, NS_WEST_NSIP, ...). Every tool then takes an appliance argument, and each appliance uses only the accounts set for it, so a tool is refused for an appliance without its account. See docs/local-mode.md.

Roles: which credentials to hand out

One server. The NetScaler accounts you put in someone's config are their role: a tool whose account is missing is not offered, and the appliance refuses anything the account's command policy does not allow, whatever the server does.

Role

Give them

Appliance users (example names)

Tools

Helpdesk / read-only

Read account

mcp_read (API only, policy mcp_read_policy)

52 read tools

Read-only plus counters

Read + nsconmsg SSH accounts

mcp_read, ns_nsconmsg_ro (CLI only)

53: adds run_nsconmsg

Operator (no config changes)

Read + admin account bound to mcp_writes only

mcp_read, mcp_admin

69: adds the 17 admin tools (16 write tools plus get_system_file); nitro_write limited to the operational commands

Admin

All four accounts: read, admin bound to sysadmin + mcp_writes, nsconmsg SSH, forensics SSH

mcp_read, mcp_admin, ns_nsconmsg_ro, mcp_forensics (CLI only)

73, every tool: the write tools, run_nsconmsg, full configuration changes through nitro_write, and the forensic tools get_core_backtrace, search_core, capture_aaad_debug

The forensic tools read process memory and the authentication debug stream as root, which can include end users' passwords. Leave the forensics account out of an admin config (70 tools) if that admin should not see them.

The exact add system cmdPolicy / add system user / bind commands for each account, what each one cannot do, and the checks behind them are in docs/local-mode.md. Hosted mode uses the same accounts per appliance; there the server holds them all and each person's Entra role (NetScaler.Reader or NetScaler.Admin) picks the tools.

A helpdesk config for Claude Code:

claude mcp add netscaler \
  -e NETSCALER_NSIP=10.0.0.1 -e NETSCALER_PEER_NSIP=10.0.0.2 \
  -e NETSCALER_USER=mcp_read -e NETSCALER_PASS=<read password> \
  -e NETSCALER_TLS_SHA256=AA...,BB... \
  -- node /path/to/netscaler-mcp-oss/dist/index.js

An admin config is the same command with the other accounts added:

  -e NETSCALER_ADMIN_USER=mcp_admin -e NETSCALER_ADMIN_PASS=<admin password> \
  -e NETSCALER_SSH_USER=ns_nsconmsg_ro -e NETSCALER_SSH_PASS=<ssh password> \
  -e NETSCALER_FORENSICS_USER=mcp_forensics -e NETSCALER_FORENSICS_PASS=<forensics password> \
  -e NETSCALER_SSH_SHA256=SHA256:...,SHA256:... \

Tools

Read tools, on the read account (every role), plus run_nsconmsg on the nsconmsg SSH account:

Area

Tools

System

get_system_info, get_system_stats, get_crash_state, list_features, get_running_config, get_saved_config, get_config_diff, get_syslog, get_nslog_events

HA

get_ha_status (includes the firmware build on each node and whether they match)

Virtual servers

list_virtual_servers, get_virtual_server, get_virtual_server_stats (LB, CS, Gateway and GSLB, including GSLB domain bindings)

Services

list_services, get_service, list_service_groups, get_service_group_members, list_down_services, get_monitor_details

SSL

list_ssl_certificates, get_ssl_certificate, list_ssl_profiles, get_ssl_vserver_config, audit_ssl_posture (old protocols, weak ciphers by name, expiring certs, missing intermediates across all SSL vservers)

Network

list_ip_addresses, list_vlans, list_routes, get_interface_stats, test_reachability (ping or traceroute from the appliance, optionally from a SNIP; fixed small probes)

DNS / GSLB

get_dns_config, list_dns_records, list_gslb_sites, list_gslb_services, get_gslb_sync_status

Authentication

diagnose_auth (follows a Gateway's authentication profile to its nFactor authentication vserver), trace_nfactor_flow, get_auth_vserver_full, get_auth_objects (LDAP, SAML, RADIUS and OAuth actions, SAML and OAuth IdP profiles, policy labels, login schemas, authentication vservers, global AAA parameters: list a kind or get one by name), list_ldap_policies, list_saml_policies, list_radius_policies, list_cert_auth_policies

Gateway

get_gateway_sessions (AAA sessions and ICA connections, by user or domain), get_gateway_session_policies

Security posture

audit_admin_access (users, groups, command policies, superuser-equivalent accounts, live management sessions), check_management_exposure (management access on SNIPs/VIPs, plain-HTTP GUI, telnet, FTP)

Troubleshooting

trace_vserver_health, search_config, list_policies_with_hits, check_policy_coverage (which Gateway and authentication vservers a responder or rewrite policy is NOT bound to), check_log_actions (log actions whose messages no syslog or nslog path will accept)

Counters

run_nsconmsg (needs the nsconmsg SSH account)

Anything else

nitro_get: read any NITRO config or stat resource by name, such as systemuser, systemsession, nsip, auditsyslogaction, appfwprofile or stat aaa. Refuses resources that return file contents or key material, run something, or are unbounded

Write tools, on the admin account (only when it is configured locally, or for the NetScaler.Admin role hosted). The forensic tools are in this table too, but they use only the forensics SSH account, not the admin account (a read + forensics config offers 55 tools):

Tool

What it does

Blast radius

force_ha_failover

Swaps primary and secondary

Brief traffic interruption on every vserver

force_ha_sync

Pushes config from primary to secondary

Whole appliance config

save_config

save ns config

Persists every unsaved change, including other admins'

enable_disable_vserver

Takes a vserver in or out of service

That vserver

enable_disable_service

Drains or restores a service

That service

enable_disable_server

Drains or restores a server object

Every service bound to that server

drain_service_group_member

Drains or restores one service group member (server + port)

That member, in every vserver the group is bound to

create_backup

create system backup, basic or full

Disk under /var/ns_sys_backup. Restore is not offered

kill_admin_session

Ends one management session by sid, only if the username matches

That session. The account can log straight back in

update_ssl_certificate

Replaces a cert-key pair in place, keeping bindings

Every vserver bound to that certkey

kill_gateway_session

Logs one user off Gateway: AAA sessions plus ICA, PCoIP and RDP connections

One username. No domain, so the same name in two tenants is logged off in both. They can sign straight back in

block_ip_acl / unblock_ip_acl

Drops one public IP or /24 with an ACL this tool owns

Every vserver and the NSIP. Refuses private ranges and NETSCALER_BLOCK_PROTECT

start_nstrace / stop_nstrace

Packet capture limited to 1-4 IPs, one size-capped file

Disk under /var/nstrace. Stop is box-wide

get_system_file

Reads any file the admin account can see

Can read private keys under /nsconfig/ssl, so it is gated like a write

get_core_backtrace, search_core, capture_aaad_debug

Fixed commands as root over the forensics SSH account: gdb bt on a core, grep a core for a marker, read the nsaaad debug pipe for up to 120 s

Output can include process memory and authentication traffic (redacted, but sensitive). The account's policy admits only these command shapes

nitro_write

Any configuration change NITRO supports: add, set, unset, rm, bind, unbind, actions. Previews the exact request by default; sends only with preview: false

Anything the NITRO user's command policy allows. Refuses reboot, shutdown, firmware install, system backups (use create_backup; restore is not offered), file writes, key material, cluster changes, session kills, nsconfig (save and clear config; use save_config) and the dynamic routing CLI (dedicated tools cover the safe versions). Changes are unsaved until save_config

Security

Read this before connecting it to a production appliance.

  • Give it its own NetScaler accounts, one per job, each bound to the command policy in docs/local-mode.md: a read account that cannot write or read key material, an admin account for write tools only, and CLI-only SSH accounts limited to exact command shapes. The appliance's command policy is the hard limit. This server's own gating sits above it, not instead of it.

  • Approve every write. Read tools return text an outsider controls (Gateway usernames, request strings, User-Agents in logs), and a model that reads it can be steered. Write tools carry the MCP destructiveHint annotation; configure your client to ask before each one, or do write work in a session that is not reading logs.

  • Secrets are redacted before anything reaches the model: password, key and secret fields in NITRO responses, the matching flags in running and saved config text, system user hashes, private-key blocks, SNMP community strings and credentials in URLs. Forensic output also masks form and JSON passwords, Authorization headers and NSC_* session cookies. The redaction is pattern-based, so treat core and debug output as sensitive. get_system_file returns binary files as unredacted base64.

  • Pin certificates. NSIP management certificates are usually self-signed, so without NETSCALER_TLS_SHA256 the server accepts any certificate and the NITRO credentials could go to an impostor on the path. The same applies to SSH and NETSCALER_SSH_SHA256. Local mode warns on stderr when it runs unpinned; hosted mode refuses to start.

  • Writes are off by default. Readers get the full read surface; Admins get nitro_write, which can change any configuration the admin account's command policy allows, plus narrow tools for common operations. Nothing here runs arbitrary CLI or shell commands, writes files or reboots. The command policy you bind to the admin account is the real limit: give it only what your Admins should be able to change.

  • Tool output goes to your model provider. Running config, session lists and logs contain hostnames, IPs and usernames. Use a provider and account your organisation has approved for that data.

  • run_nsconmsg and the forensic tools build only fixed command shapes. The appliance's command policy for each account admits exactly those shapes and nothing else. Their output is redacted like every NITRO response.

Report vulnerabilities as described in SECURITY.md.

Development

npm run dev     # run from TypeScript via tsx
npm run build   # tsc -> dist/
npm test        # after npm run build: hosted mode against a fake NITRO endpoint, local multi-appliance tool gating, nitro_write planning, redaction, forensic command shapes (needs openssl)

Check every NITRO resource and field used in src/tools/ against the NITRO OpenAPI spec for your build. Download the spec from Citrix and extract it under spec/ (gitignored). It is Citrix content and is not redistributed here.

License

MIT. See LICENSE. Not affiliated with or endorsed by Cloud Software Group. NetScaler and Citrix are trademarks of their respective owners.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • network_medic

    tanay473
    F
    license
    Not graded
    quality
    D
    maintenance
    Autonomous network monitoring and auto-remediation MCP server for Claude Desktop, enabling observation, planning, human-approved execution, verification, and session summarization.
    1
    -

  • netsuite-mcp

    yanivshoval0104
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that exposes NetSuite REST Record API tools (create, read, update, delete, SuiteQL query, metadata lookup) plus SDF tools for creating custom fields, enabling Claude to manage NetSuite records and configurations.
    3 npm
    MIT