apic-mcp-server

beletea/apic-mcp-server

3.2

If you are the rightful owner of apic-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The APIC-MCP-Server is a comprehensive Model Context Protocol (MCP) server designed for managing and analyzing Cisco ACI fabrics, providing a robust interface for network administrators and developers.

Tools
5
Resources
0
Prompts
0

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>
  1. 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)

  1. 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

  1. 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.

  1. 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
  1. 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')
"
  1. 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: "Authenticate to my APIC and show fabric health"
Ask: "What bridge domains exist in tenant 'Web-Services'?"
Ask: "Check PSIRT advisories for my ACI switches"
Ask: "Generate a report analyzing the 'Database' tenant"

💡 Usage Examples

Basic Tenant Analysis

# Get tenant overview
tenants = get_tenants(include_children=True)

# Analyze networking
bridge_domains = get_bridge_domains(tenant_name="MyTenant")
vrfs = get_vrfs(tenant_name="MyTenant")

# Security analysis
contracts = get_contracts(tenant_name="MyTenant")
denies = get_contract_denies_for_tenant(tenant_name="MyTenant")

Security Monitoring

# Check for contract violations
denies = get_contract_denies_for_tenant("production")
if denies['deny_count'] > 0:
    print(f"Found {denies['deny_count']} security violations")
    
# PSIRT vulnerability check
psirt_result = verify_apic_vulnerability()
aci_advisories = check_cisco_aci_switches_psirt("5.2(3e)")

Documentation Generation

# Generate comprehensive tenant report
analysis_content = """
# Tenant Analysis Results
... (analysis content)
"""

doc_result = create_tenant_analysis_document(
    analysis_content=analysis_content,
    tenant_name="Production",
    output_filename="production_analysis"
)

🔧 Development Guide

Project Structure

<your-project-directory>/
├── apic_mcp_server.py      # Main MCP server with 60+ tools
├── auth_utils.py           # APIC authentication utilities
├── .env.template           # Environment template file
├── README.md               # Project documentation
├── requirements.txt        # Project dependencies
├── LICENSE                 # Project license
└── .vscode/                # VS Code configuration (you need to create this folder for VS Code integration)
    ├── mcp.json            # MCP server configuration

Adding New Tools

  1. Define the Tool Function
@mcp.tool()
def my_new_tool(parameter1: str, parameter2: Optional[int] = None) -> Dict[str, Any]:
    """
    Description of what this tool does.
    
    :param parameter1: Description of parameter1
    :param parameter2: Optional description of parameter2
    :return: Dictionary with results
    """
    try:
        authenticator = get_authenticator()
        
        if not authenticator.token:
            return {
                "status": "error",
                "message": "Not authenticated. Please authenticate first."
            }
        
        # Your tool logic here
        result = authenticator.make_authenticated_request("/api/your-endpoint.json")
        
        return {
            "status": "success",
            "data": result
        }
        
    except Exception as e:
        return {
            "status": "error",
            "message": f"Tool failed: {str(e)}"
        }
  1. Add Error Handling
  • Always check authentication status
  • Use try-catch blocks for API calls
  • Return consistent response format
  • Log errors appropriately
  1. Document the Tool
  • Add clear docstrings
  • Include parameter descriptions
  • Provide usage examples
  • Update this README

Code Style Guidelines

  • PEP 8 Compliance: Follow Python coding standards
  • Type Hints: Use type annotations for all functions
  • Error Handling: Implement comprehensive error handling
  • Documentation: Document all functions and classes
  • Logging: Use appropriate logging levels

Testing

# Run basic functionality test
python -c "
import asyncio
from apic_mcp_server import mcp

async def test():
    print('MCP Server loaded successfully')
    
asyncio.run(test())
"

🐛 Troubleshooting

Common Issues

1. Authentication Failures
Error: "Authentication failed: Invalid credentials"

Solutions:

  • Verify APIC URL is correct and accessible
  • Check username/password in .env file
  • Ensure APIC certificate is trusted (set VERIFY_SSL=false for testing)
  • Check network connectivity to APIC management interface
2. SSL Certificate Issues
Error: "SSL: CERTIFICATE_VERIFY_FAILED"

Solutions:

# Temporary fix for testing
export PYTHONHTTPSVERIFY=0

# Or set in .env
APIC_VERIFY_SSL=false
3. Module Import Errors
Error: "ModuleNotFoundError: No module named 'mcp'"

Solutions:

# Install missing dependencies
pip install -r requirements.txt

# Or using uv
uv pip install -r requirements.txt

# Verify installation
python -c "import mcp; print('MCP installed successfully')"
4. APIC API Timeouts
Error: "Request timeout"

Solutions:

  • Check network latency to APIC
  • Verify APIC is not overloaded
  • Increase timeout in auth_utils.py
  • Check firewall rules
5. Permission Denied
Error: "Insufficient privileges"

Solutions:

  • Verify user has appropriate APIC privileges
  • Check user role assignments
  • Use admin account for testing
  • Review RBAC policies

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Environment Validation

# Check Python version
python --version  # Should be 3.12+ for best compatibility

# Verify dependencies
pip list | grep -E "(requests|mcp|fastmcp)"

# Test APIC connectivity
curl -k https://your-apic.com/api/aaaLogin

Performance Tuning

  • Connection Pooling: Reuse APIC sessions
  • Caching: Cache frequently accessed data
  • Pagination: Use pagination for large datasets
  • Filtering: Apply server-side filtering when possible

Logs and Monitoring

# Enable detailed logging
import logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

🤝 Contributing

How to Contribute

  1. Fork the Repository
  2. Create Feature Branch with descriptive name 
    git checkout -b feature/new-feature
  3. Make Changes
    • Follow code style guidelines
    • Add comprehensive tests
    • Update documentation
  4. Commit Changes 
    git commit -m "Add new feature"
  5. Push to Branch 
    git push origin feature/new-feature
  6. Open Pull Request

Development Setup

# Clone your fork
git clone https://github.com/yourusername/mcp-server.git
cd mcp-server

# Install development dependencies
pip install -r requirements.txt
pip install black flake8 pytest

Areas for Contribution

  • New APIC Tools: Add support for additional APIC classes / use cases
  • Enhanced Analysis: Improve fabric object analysis algorithms
  • Documentation: Improve examples and tutorials
  • Testing: Add comprehensive test suite
  • Performance: Optimize API calls and caching

📝 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

  • Issues:
  • Documentation: This README and inline code comments

🔗 Related Resources

Made with ❤️ for network automation and ACI management