🧠 Cisco ACI Intelligent Explorer — MCP Server

An AI-powered Model Context Protocol (MCP) server that lets any AI assistant (Claude, Cursor, VS Code Copilot, etc.) query and explore your Cisco ACI fabric in natural language.

🌟 What Is This?

This project bridges Cisco ACI (Application Centric Infrastructure) and AI assistants through the Model Context Protocol (MCP). Instead of manually browsing the APIC GUI or writing REST API calls, you can simply ask your AI:

"Which Bridge Domains have Unicast Routing disabled but are still attached to an L3Out?" "Show me all interfaces on node-101 that are DOWN and explain why." "What BGP neighbors are configured on leaf-1 and how many are established?"

The MCP server translates these questions into precise APIC REST API calls and returns structured answers.

Related MCP server: now-sdk-ext-mcp

🏗️ Architecture

┌─────────────────────┐        MCP / SSE          ┌────────────────────────┐
│   AI Client         │ ◄──────────────────────►  │  ACI MCP Server        │
│  (Claude, Cursor,   │     (127.0.0.1:9000)      │  aci_mcp_server.py     │
│   VS Code, etc.)    │                           │                        │
└─────────────────────┘                           │  ┌──────────────────┐  │
                                                  │  │  RAG Engine      │  │
                                                  │  │  (Semantic Search│  │
                                                  │  │   over ACI MIM)  │  │
                                                  │  └──────────────────┘  │
                                                  │                        │
                                                  │  ┌──────────────────┐  │
                                                  │  │  APIC REST API   │  │
                                                  │  │  Live Queries    │  │
                                                  │  └──────────────────┘  │
                                                  └────────┬───────────────┘
                                                           │ HTTPS
                                                  ┌────────▼───────────────┐
                                                  │   Cisco APIC           │
                                                  │   (your fabric)        │
                                                  └────────────────────────┘

📁 Project Structure

cisco-aci-mcp-server/
│
├── aci_mcp_server.py          ← 🚀 Main MCP Server (run this daily)
├── apic_config.py             ← 🔑 APIC credentials (configure before first use)
├── requirements.txt           ← 📦 Python dependencies (pip install -r requirements.txt)
│
├── mcp_config/
│   ├── aci_rag_dataset.json   ← ACI class knowledge base (~2.4 MB, 1000+ classes)
│   ├── aci_rag_embeddings.npy ← Pre-computed semantic embeddings (~9 MB)
│   └── aci_filters.json       ← APIC query filter reference guide
│
├── download_classes.py        ← 🔄 One-time: downloads ACI class metadata from Cisco DevNet
├── build_rag_dataset.py       ← 🔄 One-time: builds the RAG knowledge base
│
└── aci_advanced_test_results.md   ← Sample: 32 real-world scenario test output (Markdown)

🛠️ Available MCP Tools

The server exposes 12 tools to the AI client:

⚡ Quick Start

1. Prerequisites

• Python 3.10+

• Access to a Cisco APIC (or use the free Cisco DevNet Sandbox)

• An AI client that supports MCP over SSE (Claude Desktop, Cursor, VS Code with MCP extension, etc.)

2. Install Dependencies

pip install -r requirements.txt

Or install individually:

pip install fastmcp httpx sentence-transformers numpy urllib3

3. Configure Your APIC

Edit apic_config.py:

APIC_SERVERS = [
    {
        "apicname": "myFabric",           # Name you choose (used in queries)
        "url": "https://192.168.10.10",   # Your APIC IP or FQDN
        "username": "admin",
        "password": "YourPassword"
    }
]

⚠️ Security: Never commit real credentials to a public repository. Use environment variables or a secrets manager in production deployments.

4. Start the MCP Server

python aci_mcp_server.py

Expected output:

INFO: Starting MCP server 'Cisco ACI Intelligent Explorer Agent' with transport 'sse' on http://127.0.0.1:9000/sse
INFO: Uvicorn running on http://127.0.0.1:9000

5. Connect Your AI Client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}

🔄 Script Reference — When to Run What

The main server (aci_mcp_server.py) is the only file you run day-to-day. The other scripts are one-time setup or periodic update tools:

aci_mcp_server.py — Run Every Time You Use the System

python aci_mcp_server.py

• Starts the MCP server on http://127.0.0.1:9000/sse

• Loads the RAG dataset and semantic model on startup (~10-15 seconds)

• Restart this if you: edit apic_config.py, add new APIC servers, or update mcp_config/ files

download_classes.py — Run Once at Setup (or on ACI Version Upgrade)

python download_classes.py

• Downloads ACI class metadata from Cisco DevNet documentation

• Saves JSON files into aci_classes_json/ directory

• When to re-run: Only when Cisco releases a new ACI software version and you want updated class definitions

build_rag_dataset.py — Run After download_classes.py

python build_rag_dataset.py

• Reads all JSON files from aci_classes_json/

• Enriches data with a curated Acronyms/Synonyms Dictionary (29 entries: VRF, EPG, BD, AEP, vPC, LACP, OSPF, CDP, STP, VMM domain, L3Out EPG, Filter/ACL, Contract Subject, VLAN Pool and more)

• Dynamically extracts configurable properties (isConfigurable=True) for all classes to prevent system noise

• Builds mcp_config/aci_rag_dataset.json (the knowledge base)

• Computes vector embeddings → mcp_config/aci_rag_embeddings.npy

• When to re-run: After download_classes.py, or if you modify class data / synonym mappings

Full Setup Flow (First-Time or ACI Version Update)

Step 1:  python download_classes.py
         └─ Downloads class metadata from Cisco DevNet → aci_classes_json/

Step 2:  python build_rag_dataset.py
         └─ Builds knowledge base → mcp_config/aci_rag_dataset.json
         └─ Computes embeddings   → mcp_config/aci_rag_embeddings.npy

Step 3:  python aci_mcp_server.py
         └─ Server ready at http://127.0.0.1:9000/sse

💡 Tip: The mcp_config/ files are already included in this repository. For most users, you only need Step 3 (start the server directly). Steps 1 and 2 are only needed when updating for a new Cisco ACI version.

🔒 Security Design

💬 Example Queries

Once connected, ask your AI natural language questions:

"Show me all tenants in the fabric"
"Which EPGs are providing the 'web-contract'?"
"Find all Bridge Domains without subnets in tenant CHA_PCIDSS_TN"
"What is the operational status of all ports on node-101?"
"Are there any faults with severity 'critical' or 'major'?"
"Show BGP peer configuration for node-101 and compare to runtime state"
"Which LLDP policies have TX disabled and where are they applied?"
"Find EPGs with static port bindings but no active endpoints"
"What are the active VTEP tunnels and which nodes do they belong to?"

📋 Requirements

fastmcp>=0.1.0
httpx
sentence-transformers
numpy
urllib3

Install all at once:

pip install fastmcp httpx sentence-transformers numpy urllib3

🧪 Test Results

See aci_advanced_test_results.md for a complete diagnostics test run output.

A total of 32 real-world operational and audit scenarios (including advanced troubleshooting, logical relation tracing, DN drill-down exploration, and example query runs) were successfully executed against the Cisco DevNet Sandbox APIC. The results file contains full details of the tool call flows, arguments, and live APIC responses, demonstrating successful end-to-end execution of the MCP server.

🤝 Contributing & Feedback

Contributions, issues, and feature requests are welcome! Feel free to:

• Open an Issue to report bugs or suggest new features.

• Start a Discussion (if enabled) if you have questions or ideas to share.

• Submit a Pull Request (PR) to improve the codebase.

For direct feedback, you can reach out via email: ciftcigkhn@gmail.com

📄 License

This project is provided for educational and operational use under the MIT License. Not affiliated with or endorsed by Cisco Systems, Inc.

🇹🇷 Türkçe Dokümantasyon

Türkçe kullanım kılavuzu için bkz: README_TR.md