Code ExchangeSearch AI reposRepository
Search allSubmit project

Catalyst Center MCP Server

Connect an MCP-compatible AI client to your Cisco Catalyst Center instance. This
standalone server exposes the APIs in its bundled Catalyst Center tool catalog
over a local, streamable HTTP Model Context Protocol (MCP)
endpoint.

Use it to let an AI client retrieve and analyze Catalyst Center data, such as
inventory, device health, wireless experience, software, and compliance
information, without building a custom integration for each API.

What Is MCP?

MCP is an open standard that lets AI clients discover and call structured tools
at runtime. In this integration, the client chooses a Catalyst Center tool,
supplies its parameters, and the server authenticates to Catalyst Center and
returns the API result. The client can then sequence multiple tools to answer a
broader operational question.

This server exposes a versioned bundle of generated Catalyst Center API tools, aligned with the Catalyst Center release and its API operations.

Before You Start

Select the release branch that matches your Catalyst Center version before
building or running the server:

git clone https://github.com/cisco-en-programmability/catc-mcp-oss
cd catc-mcp-oss
git checkout release/<M.N.P.Q>

You need:

  • Network access from the server host to your Catalyst Center instance
  • A Catalyst Center username and password
  • Docker
  • An MCP-compatible client, such as Claude Desktop, Cursor, VS Code, or Codex

Use a Dedicated, Least-Privilege Account

The server authenticates to Catalyst Center with the configured username and
password and executes tools with that account's permissions. It does not add an
authorization layer or enforce read-only access. The bundled catalog includes
generated API operations and may include operations that change configuration.

Create a dedicated Catalyst Center account with the minimum permissions needed
for the tasks you intend to perform. Treat every client connected to this server
as able to request any bundled operation that account is allowed to execute.

Keep the MCP endpoint private. The examples bind it to 127.0.0.1; do not
expose it on an untrusted network without adding appropriate network controls
and authentication in front of it.

Quick Start

From a clone of this repository, configure the target controller and account:

export CATALYST_CENTER_HOST="https://catalyst-center.example.com"
export CATALYST_CENTER_USERNAME="mcp-service-account"
export CATALYST_CENTER_PASSWORD="replace-with-a-password"
export CATALYST_CENTER_VERIFY_SSL=false

CATALYST_CENTER_HOST may be a hostname, IP address, or URL. When no scheme is
provided, the server uses https://.

Build the image and start the server on the local loopback interface:

docker build -t catalyst-center-mcp:local .
docker run --rm -p 127.0.0.1:7001:7001 \
  -e CATALYST_CENTER_HOST \
  -e CATALYST_CENTER_USERNAME \
  -e CATALYST_CENTER_PASSWORD \
  -e CATALYST_CENTER_VERIFY_SSL=false \
  catalyst-center-mcp:local

The MCP endpoint is:

http://localhost:7001/v1/mcp

In a second terminal, verify the process and required credential configuration:

curl http://localhost:7001/v1/health
curl http://localhost:7001/v1/readiness

/v1/health confirms that the server process is running. /v1/readiness
validates that the required Catalyst Center configuration is present; it does
not make a Catalyst Center API request.

TLS note: Keep CATALYST_CENTER_VERIFY_SSL=true for controllers with a
trusted certificate. Set it to false only when you understand and accept
the risk of bypassing certificate validation, such as a lab controller with a
self-signed certificate.

Runtime Modes

The examples below use the Docker image built in Quick Start.

HTTP(S)

The Quick Start command runs the streamable HTTP endpoint on the local loopback
interface:

http://localhost:7001/v1/mcp

Use plain HTTP for local testing or when TLS is terminated by external
infrastructure. HTTPS is recommended when exposing the MCP server beyond the
local machine. For enterprise deployments, prefer terminating TLS outside this
container using the organization's standard ingress, reverse proxy, service
mesh, API gateway, or load balancer. Use centrally managed certificates,
rotation, policy enforcement, and audit controls there, while keeping this
container on its default internal HTTP listener unless direct TLS termination in
the container is explicitly required.

For direct container TLS termination, mount the certificate and key read-only and
pass Uvicorn SSL options:

docker run --rm -p 127.0.0.1:7001:7001 \
  -v "$PWD/certs:/certs:ro" \
  -e CATALYST_CENTER_HOST \
  -e CATALYST_CENTER_USERNAME \
  -e CATALYST_CENTER_PASSWORD \
  -e CATALYST_CENTER_VERIFY_SSL=false \
  catalyst-center-mcp:local \
  python3 -m uvicorn catalyst_center_mcp.main:app \
    --host 0.0.0.0 \
    --port 7001 \
    --ssl-keyfile /certs/localhost-key.pem \
    --ssl-certfile /certs/localhost-cert.pem

The direct HTTPS endpoint is:

https://localhost:7001/v1/mcp

Generating SSL Certificates

For local development or test environments, you can generate a self-signed
certificate with OpenSSL:

mkdir -p certs
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout certs/localhost-key.pem \
  -out certs/localhost-cert.pem \
  -days 365 \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

This creates the certificate and key expected by the direct HTTPS Docker example:

certs/localhost-cert.pem
certs/localhost-key.pem

Use enterprise-managed certificates for shared, production, or externally
reachable deployments.

STDIO

Use STDIO when your MCP client launches and communicates with the server as a
child process instead of connecting to an already-running HTTP server:

docker run --rm -i \
  -e CATALYST_CENTER_HOST \
  -e CATALYST_CENTER_USERNAME \
  -e CATALYST_CENTER_PASSWORD \
  -e CATALYST_CENTER_VERIFY_SSL \
  catalyst-center-mcp:local \
  fastmcp run catalyst_center_mcp/main.py:mcp --transport stdio

Use -i so stdin remains attached. Do not publish ports for STDIO mode.

Connect an MCP Client

Start the server first, then add http://localhost:7001/v1/mcp as an HTTP MCP
server in your client. The local server does not require an inbound header; it
authenticates to Catalyst Center with the environment variables above.

Claude Desktop

Add this server to claude_desktop_config.json:

{
  "mcpServers": {
    "catalyst-center": {
      "url": "http://localhost:7001/v1/mcp"
    }
  }
}

For STDIO access, add this server to claude_desktop_config.json:

{
  "mcpServers": {
    "catalyst-center": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CATALYST_CENTER_HOST",
        "-e", "CATALYST_CENTER_USERNAME",
        "-e", "CATALYST_CENTER_PASSWORD",
        "-e", "CATALYST_CENTER_VERIFY_SSL",
        "catalyst-center-mcp:local",
        "fastmcp",
        "run",
        "catalyst_center_mcp/main.py:mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "CATALYST_CENTER_HOST": "https://catalyst-center.example.com",
        "CATALYST_CENTER_USERNAME": "mcp-service-account",
        "CATALYST_CENTER_PASSWORD": "replace-with-a-password",
        "CATALYST_CENTER_VERIFY_SSL": "false"
      }
    }
  }
}

Cursor

Add this server to .cursor/mcp.json:

{
  "mcpServers": {
    "catalyst-center": {
      "url": "http://localhost:7001/v1/mcp"
    }
  }
}

For STDIO access, use:

{
  "mcpServers": {
    "catalyst-center": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CATALYST_CENTER_HOST",
        "-e", "CATALYST_CENTER_USERNAME",
        "-e", "CATALYST_CENTER_PASSWORD",
        "-e", "CATALYST_CENTER_VERIFY_SSL",
        "catalyst-center-mcp:local",
        "fastmcp",
        "run",
        "catalyst_center_mcp/main.py:mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "CATALYST_CENTER_HOST": "https://catalyst-center.example.com",
        "CATALYST_CENTER_USERNAME": "mcp-service-account",
        "CATALYST_CENTER_PASSWORD": "replace-with-a-password",
        "CATALYST_CENTER_VERIFY_SSL": "false"
      }
    }
  }
}

VS Code

Add this server to .vscode/mcp.json:

{
  "servers": {
    "catalyst-center": {
      "type": "http",
      "url": "http://localhost:7001/v1/mcp"
    }
  }
}

For STDIO access, use:

{
  "servers": {
    "catalyst-center": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CATALYST_CENTER_HOST",
        "-e", "CATALYST_CENTER_USERNAME",
        "-e", "CATALYST_CENTER_PASSWORD",
        "-e", "CATALYST_CENTER_VERIFY_SSL",
        "catalyst-center-mcp:local",
        "fastmcp",
        "run",
        "catalyst_center_mcp/main.py:mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "CATALYST_CENTER_HOST": "https://catalyst-center.example.com",
        "CATALYST_CENTER_USERNAME": "mcp-service-account",
        "CATALYST_CENTER_PASSWORD": "replace-with-a-password",
        "CATALYST_CENTER_VERIFY_SSL": "false"
      }
    }
  }
}

Codex

Add this server to ~/.codex/config.toml:

[mcp_servers.catalyst_center]
url = "http://localhost:7001/v1/mcp"

For STDIO access, use:

[mcp_servers.catalyst_center]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "-e", "CATALYST_CENTER_HOST",
  "-e", "CATALYST_CENTER_USERNAME",
  "-e", "CATALYST_CENTER_PASSWORD",
  "-e", "CATALYST_CENTER_VERIFY_SSL",
  "catalyst-center-mcp:local",
  "fastmcp",
  "run",
  "catalyst_center_mcp/main.py:mcp",
  "--transport",
  "stdio",
]

[mcp_servers.catalyst_center.env]
CATALYST_CENTER_HOST = "https://catalyst-center.example.com"
CATALYST_CENTER_USERNAME = "mcp-service-account"
CATALYST_CENTER_PASSWORD = "replace-with-a-password"
CATALYST_CENTER_VERIFY_SSL = "false"

Example Use Cases

The examples below tell the client the outcome you need. It will select the
generated Catalyst Center tools and sequence calls as needed. The exact tools
available depend on the checked-in bundle.

Inventory and Device Health Review

"Summarize device inventory and health for the Global/San Jose site. Identify
devices with POOR health, group them by device role, and show the highest
priority issues to investigate first. Include the device name, management IP,
and health category."

The client can resolve the site, retrieve device-health data, then use device
details to make the results actionable.

Wireless Client Experience Investigation

"Investigate wireless client experience at the HQ building over the last 24
hours. Identify the access points, SSIDs, or clients with the most degraded
experience, explain the apparent pattern from the available data, and list
the next checks an engineer should perform."

The client can first resolve the site and then retrieve the appropriate
wireless, client, and health records for the requested time range.

Software and Compliance Review

"Review the network for software and compliance risk. List devices with
compliance issues, relevant field notices or security advisories, and their
current software details. Prioritize the findings by likely operational
impact. Do not make any changes."

Explicitly state the intended safety boundary in prompts. The client can use
read-oriented tools to gather the evidence, but the server does not prevent it
from selecting a bundled operation that the configured account can execute.

Policies and Support

  • LICENSE contains more information about the Apache 2.0 license
    under which this software is distributed.
  • NOTICE describes the Cisco Catalyst Center and API terms that
    apply when this software communicates with Catalyst Center. Those terms are
    separate from the open-source license governing this code.
  • SECURITY explains how to report a security issue privately.
  • CONTRIBUTING describes the project's issue and contribution
    policy.
View code on GitHub
Related code repos

    Code Exchange Community

    Get help, share code, and collaborate with other developers in the Code Exchange community.View Community
    Disclaimer:
    Please note that some of the repositories in Code Exchange may be enabled to interact with third-party Generative AI platforms outside of Cisco’s control, and users should review those third-party terms and privacy statements to understand how data is processed, stored or used, including input data.