MCP (Model Context Protocol) for Cisco APIC

This project provides a simple MCP (Model Context Protocol) server that interacts with a Cisco APIC controller. If you'd like to understand how this works in detail, please check out this blog post

• Tested with Claude Desktop and Visual Studio Code in Agent mode with Copilot.
• The server runs in STDIO mode, intended for local execution.

Features

• Multiple tools for APIC interaction (see app/main.py for details).
• Easily configurable via environment variables.
• Handles large tenant configurations by saving them to local files (bypasses Claude Desktop's 1MB response limit).
• Configuration management tools to list and delete saved configurations.

Setup

Note: This project is designed to run inside WSL (Windows Subsystem for Linux). If you're on Windows, ensure WSL is installed and configured before proceeding.

1. Install UV - UV Installation Guide

   # Inside WSL or on macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows (if not using WSL)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Install dependencies using UV:

   uv sync

3. Specify APIC credentials in the app/.env file (create from example):

   cp app/.env.example app/.env
   # Edit app/.env with your APIC credentials

4. Register the MCP server with Claude Desktop or VS Code.

   For Claude Desktop:

   Add this configuration to your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   If running inside WSL (Windows Subsystem for Linux):

   {
     "mcpServers": {
       "cisco-apic": {
         "command": "wsl",
         "args": [
           "bash",
           "-c",
           "cd /home/cpaggen/APIC-MCP && uv run app/main.py"
         ]
       }
     }
   }

   Note: Replace /home/cpaggen/APIC-MCP with the actual WSL path to this project.

   If running directly on macOS/Linux:

   {
     "mcpServers": {
       "cisco-apic": {
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/APIC-MCP",
           "run",
           "app/main.py"
         ]
       }
     }
   }

   Note: Replace /path/to/APIC-MCP with the actual path to this project.

   The MCP server will read credentials from the app/.env file.

   For VS Code:

   Create a .vscode/mcp.json file in your workspace:

   If running inside WSL:

   {
     "servers": {
       "cisco-apic": {
         "type": "stdio",
         "command": "wsl",
         "args": [
           "bash",
           "-c",
           "cd /home/cpaggen/APIC-MCP && uv run app/main.py"
         ]
       }
     }
   }

   Note: Replace /home/cpaggen/APIC-MCP with the actual WSL path to this project.

   If running directly on macOS/Linux:

   {
     "servers": {
       "cisco-apic": {
         "type": "stdio",
         "command": "uv",
         "args": [
           "--directory",
           "/path/to/APIC-MCP",
           "run",
           "app/main.py"
         ]
       }
     }
   }

   Note: Replace /path/to/APIC-MCP with the actual path to this project.

5. Instruct Claude Desktop or VS Code to use it:

   • See Claude Desktop Quickstart
   • See VS Code Copilot MCP Servers

6. Run the MCP server:

   uv run app/main.py

   Or with MCP CLI tools:

   uv run --with "mcp[cli]" mcp run app/main.py

Handling Large Tenant Configurations

The get_tenant_config tool can retrieve very large configurations that exceed Claude Desktop's 1MB response limit. To handle this, the tool saves the full configuration to a local file and returns a summary with the file path.

Configuration Storage

By default, configurations are saved to ./apic_configs/ in the project directory. You can customize this location by setting the APIC_CONFIG_DIR environment variable in your app/.env file:

APIC_CONFIG_DIR=/path/to/your/configs

Available Tools

1. get_tenant_config(tenant_name, query_depth, target_class)

   • Retrieves tenant configuration and saves it to a file
   • Returns a summary with file path, size, and object counts
   • Optional parameters to limit query depth or filter by class

2. list_saved_configs()

   • Lists all saved configuration files
   • Shows filename, size, and modification time

3. delete_saved_config(filename)

   • Deletes a specific saved configuration file

Usage Examples

# Get full tenant configuration (saved to file)
Ask Claude: "Get the configuration for tenant 'production'"

# Claude will use get_tenant_config() and return a summary like:
{
  "status": "success",
  "tenant_name": "production",
  "config_file": "/home/user/APIC-MCP/apic_configs/production_20260103_143022.json",
  "file_size_mb": 2.45,
  "children_summary": {
    "fvBD": 15,
    "fvAp": 8,
    "fvCtx": 3
  }
}

# Claude can then read and analyze the saved file
Ask Claude: "Read the configuration file and tell me about the bridge domains"

# List all saved configurations
Ask Claude: "List all saved APIC configurations"

# Clean up old configurations
Ask Claude: "Delete the configuration file production_20260103_143022.json"

Filtering Large Configurations

For very large tenants, you can reduce the response size by filtering:

# Get only direct children (faster, smaller)
get_tenant_config("production", query_depth="children")

# Get configuration up to depth 2
get_tenant_config("production", query_depth="2")

# Get only Bridge Domains
get_tenant_config("production", target_class="fvBD")

# Get only Application Profiles
get_tenant_config("production", target_class="fvAp")

Docker Support

You can run the server directly using UV, or build a Docker image and run it as a container. If using Docker, adapt the mcp.json config accordingly.

Note: Local installation of MCP client tools is recommended for debugging the server code.

Screenshots

Below are some screenshots demonstrating the MCP server in action and its integration with Claude Desktop and VS Code:

MCP Server Registered	Tool Registered in Claude	Claude Tools List

MCP Server Output	Sample Question in VS Code	Sample Question in Claude

How to Use ACI Backup

These images illustrate the registration process, available tools, and example interactions.