# Apic Mcp Server

> Think Smarter. Design Smarter. Build Smarter Networks.

- **Type:** MCP server
- **Install:** `agentstack add mcp-beletea-apic-mcp-server`
- **Verified:** Pending review
- **Seller:** [beletea](https://agentstack.voostack.com/s/beletea)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [beletea](https://github.com/beletea)
- **Source:** https://github.com/beletea/apic-mcp-server
- **Website:** https://deliabtech.com/

## Install

```sh
agentstack add mcp-beletea-apic-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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:

```python
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

```bash
# 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
```python
# 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
```python
# 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**
```bash
git clone 
cd 
```

2. **Install Dependencies**

```bash
# 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**
```bash
# 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:
```bash
# 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`:
   ```json
   {
     "servers": {
       "cisco-aci-apic": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp",
           "mcp",
           "run",
           ""
         ]
       }
     }
   }
   ```
  Replace `` 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`:
   ```json
   {
     "mcpServers": {
       "cisco-aci-apic": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "mcp",
           "mcp",
           "run",
           ""
         ]
       }
     }
   }
   ```
  Replace `` 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:
  ```json
   {
     "mcpServers": {
       "cisco-aci-apic": {
         "command": "",
         "args": [
           "run",
           "--project",
           "",
           "python",
           ""
         ]
       }
     }
   }
  ```

  Replace `` with the full path to your `uv` executable, and `` 
  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**
```bash
# 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**
```bash
# 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**
```bash
# 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
```python
# 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
```python
# 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
```python
# 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
```
/
├── 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**
```python
@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)}"
        }
```

2. **Add Error Handling**
- Always check authentication status
- Use try-catch blocks for API calls
- Return consistent response format
- Log errors appropriately

3. **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

```bash
# 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:**
```bash
# 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:**
```bash
# Install missing dependencies
pip install -

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [beletea](https://github.com/beletea)
- **Source:** [beletea/apic-mcp-server](https://github.com/beletea/apic-mcp-server)
- **License:** MIT
- **Homepage:** https://deliabtech.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-beletea-apic-mcp-server
- Seller: https://agentstack.voostack.com/s/beletea
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.