Authentication

Authentication to the APIC is always performed using credentials from the .env file. The authenticate_apic MCP tool ignores any arguments passed to it and will only use the following environment variables:

APIC_URL=https://apic.example.com
APIC_USERNAME=admin
APIC_PASSWORD=mypassword
APIC_VERIFY_SSL=false

Make sure your .env file is present in the project root and contains the correct values. use .env.template as a reference. Arguments to the authenticate_apic function are ignored.

Example usage:

authenticate_apic()

This will always use the credentials from .env.

APIC-MCP-Server

A comprehensive Model Context Protocol (MCP) server for managing and analyzing Cisco ACI (Application Centric Infrastructure) fabrics. This tool provides a powerful interface for network administrators and developers to interact with Cisco APIC controllers, perform analysis, and generate detailed reports.

🚀 What is APIC-MCP-Server?

The APIC-MCP-Server is a Python-based MCP server and it provides:

• 🔌 Direct APIC Integration: Seamless authentication and communication with Cisco APIC controllers
• 📊 Comprehensive Analysis: Detailed tenant, EPG, BD, VRF, and security policy analysis
• 🔍 Security Monitoring: Contract deny logging, vulnerability checking via PSIRT API
• 📋 Documentation Generation: Automated document generation for infrastructure reports
• ⚡ Fabric Monitoring: Fabric health monitoring and troubleshooting capabilities

🏗️ Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Apps   │    │  APIC-MCP-Server │    │  Cisco APIC     │
│                 │    │                  │    │  Controllers    │
│ • VS Code       │◄──►│ • FastMCP        │◄──►│                 │
│ • Claude        │    │ • Authentication │    │ • REST API      │
│ • Custom Tools  │    │ • Analysis Tools │    │ • Policy Data   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  External APIs  │
                       │                 │
                       │ • Cisco PSIRT   │
                       │ • Field Notices │
                       │ • Vulnerability │
                       │   Database      │
                       └─────────────────┘

📦 Components

Core Components

1. apic_mcp_server.py (Main Server)

• FastMCP Framework: Primary MCP server implementation
• 20+ Tools: Comprehensive set of APIC management tools
• Document Generation: Creates professional reports

2. auth_utils.py (Authentication)

• APIC Authentication: Secure JWT token management
• Session Management: Persistent connection handling
• Error Handling: Robust authentication error recovery

Configuration Files

3. .env.template (Environment Template)

• Environment Setup: Template for environment variables
• APIC Configuration: Connection settings and credentials
• Security: PSIRT API configuration for vulnerability checking

4. .vscode/ (VS Code Integration)

• MCP Configuration: VS Code MCP server settings
• Development Setup: IDE configuration for development

# APIC Connection Settings
APIC_URL=https://your-apic.example.com
APIC_USERNAME=admin
APIC_PASSWORD=your-password
APIC_VERIFY_SSL=false

# PSIRT API Settings (Optional)
MY_PSIRT_API_URL=https://api.cisco.com/security/advisories
MY_PSIRT_CLIENT_ID=your-client-id
MY_PSIRT_CLIENT_SECRET=your-client-secret

🛠️ Available Tools

Authentication & Status

• authenticate_apic() - Authenticate to APIC controller
• get_apic_status() - Check current session status
• logout_apic() - Logout and cleanup session

Fabric Discovery

• get_tenants() - List all tenants
• get_fabric_nodes() - List fabric switches and controllers
• search_objects_by_name() - Search for specific objects

Tenant Management

• get_application_profiles() - List application profiles
• get_epgs() - List endpoint groups
• get_bridge_domains() - List bridge domains
• get_vrfs() - List VRFs
• get_contracts() - List security contracts

Security Analysis

• get_denied_logs_for_tenant() - Check audit violations
• get_contract_denies_for_tenant() - Analyze contract denies
• get_contract_permit_logs_for_tenant() - Review permitted traffic

External Connectivity

• fetch_apic_class() - Generic APIC class queries
• get_node_interface_status() - Interface operational status

Security Intelligence

• verify_apic_vulnerability() - Check APIC vulnerabilities
• check_cisco_aci_switches_psirt() - PSIRT advisory lookup
• get_apic_field_notices() - APIC field notices
• get_nexus_9000_field_notices() - Switch field notices

Documentation

• create_tenant_analysis_document() - Generate reports

⚠️ Dangerous Operations

• create_apic_object() - Create an APIC object in the fabric
• delete_apic_object() - Delete an APIC object from the fabric

Warning: These tools perform changes directly on your Cisco ACI fabric. Creating or deleting objects can disrupt production environments, cause outages, or result in data loss. Always double-check your parameters and use these tools only if you understand the impact. It is recommended to test in a non-production environment first.

Confirmation Workflow for Create/Delete Actions

For all dangerous operations (such as creating or deleting APIC objects), the MCP server enforces a confirmation workflow:

• Preview Step: When you request a create or delete action (e.g., creating a tenant or deleting an EPG), the server will first show you a preview of what will be pushed or deleted. This includes the full payload or distinguished name (DN) of the object.
• Explicit Confirmation Required: The operation will only proceed if you explicitly confirm (e.g., by replying "yes" or confirming in the UI). If you do not confirm, the action is cancelled and no changes are made.
• Safety: This workflow helps prevent accidental changes and ensures you have a chance to review all destructive or impactful actions before they are executed.

Example: Creating a Tenant

# Request to create a tenant
result = create_apic_object(parent_dn="uni", object_payload={"fvTenant": {"attributes": {"name": "mcp-server"}}}, confirm=False)
# You will receive a preview and must confirm before proceeding
if result["status"] == "pending":
    # Review the payload, then confirm
    result = create_apic_object(parent_dn="uni", object_payload={"fvTenant": {"attributes": {"name": "mcp-server"}}}, confirm=True)

Example: Deleting a Tenant

# Request to delete a tenant
result = delete_apic_object(object_dn="uni/tn-mcp-server", confirm=False)
# You will receive a preview and must confirm before proceeding
if result["status"] == "pending":
    # Review the DN, then confirm
    result = delete_apic_object(object_dn="uni/tn-mcp-server", confirm=True)

This confirmation workflow applies to all create and delete operations exposed by the MCP server.

---

🚀 Getting Started

Prerequisites

• Python 3.12+ for best compatibility
• Access to Cisco APIC controller
• Network connectivity to APIC management interface
• VS Code (for VS Code integration) or Claude Desktop (for Claude integration)

Installation

1. Clone the Repository

git clone <your-repo-url>
cd <your-project-directory>

2. Install Dependencies

# Install all dependencies
pip install -r requirements.txt

The requirements.txt includes:

• fastmcp (core MCP server framework)
• requests (HTTP client)
• python-dotenv (environment variable management)
• beautifulsoup4 (HTML parsing)
• python-docx (Word document generation)
• uvicorn (optional, async server)

pytest, flake8 (optional, for testing/linting)

3. Configure Environment

# Copy and edit environment file
cp .env.template .env
# Edit .env with your APIC and credentials
# PSIRT client id and client secret are optional but recommended for security analysis

Edit the .env file with your APIC details:

# APIC Connection Settings
APIC_URL=https://your-apic.example.com
APIC_USERNAME=admin
APIC_PASSWORD=your-password
APIC_VERIFY_SSL=false

# PSIRT API Settings (Optional)
MY_PSIRT_API_URL=https://api.cisco.com/security/advisories
MY_PSIRT_CLIENT_ID=your-client-id
MY_PSIRT_CLIENT_SECRET=your-client-secret

🔧 MCP Client Configuration

Option 1: VS Code Integration

1. Install the MCP Extension

   • Install the "Model Context Protocol" extension in VS Code
   • Or install "Claude Dev" extension which supports MCP

2. Configure MCP Server

   Create or update your VS Code .vscode/mcp.json:

   {
     "servers": {
       "cisco-aci-apic": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp",
           "mcp",
           "run",
           "<path-to-your-apic_mcp_server.py>"
         ]
       }
     }
   }
   

Replace <path-to-your-apic_mcp_server.py> with the full path to your apic_mcp_server.py file.

3. **Restart VS Code** and the MCP server will be available in your VS Code environment.

#### Option 2: Claude Desktop Integration

1. **Locate or create Claude Desktop Config**
```bash
# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json

2. Add MCP Server Configuration

   Edit claude_desktop_config.json:

   {
     "mcpServers": {
       "cisco-aci-apic": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp",
           "mcp",
           "run",
           "<full-path-to-your-apic_mcp_server.py>"
         ]
       }
     }
   }
   

Replace <full-path-to-your-apic_mcp_server.py> with the full path to your apic_mcp_server.py file. If you encounter issues with the project path, you may need to adjust the path accordingly, like this:

 {
   "mcpServers": {
     "cisco-aci-apic": {
       "command": "<full-path-to-your-uv>",
       "args": [
         "run",
         "--project",
         "<full-path-to-your-apic_mcp_server>",
         "python",
         "<full-path-to-your-apic_mcp_server.py>"
       ]
     }
   }
 }

Replace <full-path-to-your-uv> with the full path to your uv executable, and <full-path-to-your-apic_mcp_server> with the directory containing your apic_mcp_server.py.

3. Restart Claude Desktop and the APIC tools will be available in your conversations.

🧪 Testing Your Setup

1. Test Environment Variables

# Verify your .env file is loaded correctly
python -c "
import os
from dotenv import load_dotenv
load_dotenv()
print(f'APIC URL: {os.getenv(\"APIC_URL\")}')
print(f'Username: {os.getenv(\"APIC_USERNAME\")}')
"
# Ensure APIC URL and credentials are correct

2. Test MCP Server

# Verify MCP server is running
curl -X GET http://localhost:5000/mcp/status
```bash
# Basic import test
python -c "
from apic_mcp_server import mcp
print('✅ MCP Server loaded successfully')
"

3. Test APIC Connectivity

# Test network connectivity to your APIC
curl -k https://your-apic.example.com/api/class/topSystem.json

🎯 Using the APIC-MCP Server

Once configured with VS Code or Claude Desktop, you can use natural language to interact with your ACI fabric:

In VS Code with MCP Extension:

Ask: "Show me all tenants in my ACI fabric"
Ask: "List EPGs in the 'Production' tenant"
Ask: "Check for contract denies in tenant 'Production'"
Ask: "Generate a security analysis report for tenant 'DMZ'"

In Claude Desktop:

Ask: "Auth