Cisco Aci Mcp Server

身份验证

始终使用 .env 文件中的凭据进行 APIC 身份验证。authenticate_apic MCP 工具会忽略传入的所有参数，只使用以下环境变量：

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

请确保项目根目录中存在 .env 文件，且其中包含正确的值。请参考 .env.template。authenticate_apic 函数的参数会被忽略。

用法示例：

authenticate_apic()

这将始终使用 .env 中的凭据。

APIC-MCP-Server

用于管理和分析 Cisco ACI（Application Centric Infrastructure）Fabric 的综合性 Model Context Protocol（MCP）服务。此工具为网络管理员和开发者提供强大的接口，可用于与 Cisco APIC 控制器交互、执行分析并生成详细报告。

🚀 什么是 APIC-MCP-Server？

APIC-MCP-Server 是一个基于 Python 的 MCP 服务，提供以下功能：

• 🔌 直接集成 APIC：与 Cisco APIC 控制器无缝进行身份验证和通信
• 📊 综合分析：详细分析租户、EPG、BD、VRF 和安全策略
• 🔍 安全监控：记录合约拒绝日志，并通过 PSIRT API 检查漏洞
• 📋 文档生成：自动生成基础设施报告文档
• ⚡ Fabric 监控：Fabric 健康监控和故障排除功能

🏗️ 架构概览

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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      │
                       └─────────────────┘

📦 组件

核心组件

1. apic_mcp_server.py（主服务）

• FastMCP 框架：主要的 MCP 服务实现
• 20+ 个工具：全面的 APIC 管理工具集
• 文档生成：创建专业报告

2. auth_utils.py（身份验证）

• APIC 身份验证：安全管理 JWT 令牌
• 会话管理：持久化连接处理
• 错误处理：可靠地恢复身份验证错误

配置文件

3. .env.template（环境模板）

• 环境设置：环境变量模板
• APIC 配置：连接设置和凭据
• 安全性：用于漏洞检查的 PSIRT API 配置

4. .vscode/（VS Code 集成）

• MCP 配置：VS Code MCP 服务设置
• 开发设置：开发用 IDE 配置

# 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

🛠️ 可用工具

身份验证与状态

• authenticate_apic() - 向 APIC 控制器进行身份验证
• get_apic_status() - 检查当前会话状态
• logout_apic() - 注销并清理会话

Fabric 发现

• get_tenants() - 列出所有租户
• get_fabric_nodes() - 列出 Fabric 交换机和控制器
• search_objects_by_name() - 搜索指定对象

租户管理

• get_application_profiles() - 列出应用配置文件
• get_epgs() - 列出端点组
• get_bridge_domains() - 列出桥接域
• get_vrfs() - 列出 VRF
• get_contracts() - 列出安全合约

安全分析

• get_denied_logs_for_tenant() - 检查审计违规情况
• get_contract_denies_for_tenant() - 分析合约拒绝记录
• get_contract_permit_logs_for_tenant() - 查看允许通过的流量

外部连接

• fetch_apic_class() - 通用 APIC 类查询
• get_node_interface_status() - 接口运行状态

安全情报

• verify_apic_vulnerability() - 检查 APIC 漏洞
• check_cisco_aci_switches_psirt() - 查询 PSIRT 安全公告
• get_apic_field_notices() - APIC 现场通知
• get_nexus_9000_field_notices() - 交换机现场通知

文档

• create_tenant_analysis_document() - 生成报告

⚠️ 危险操作

• create_apic_object() - 在 fabric 中创建 APIC 对象
• delete_apic_object() - 从 fabric 中删除 APIC 对象

警告： 这些工具会直接更改您的 Cisco ACI fabric。创建或删除对象可能会影响生产环境、导致服务中断或造成数据丢失。请务必仔细检查参数，并且仅在了解其影响的情况下使用这些工具。建议先在非生产环境中进行测试。

创建/删除操作的确认工作流

对于所有危险操作（例如创建或删除 APIC 对象），MCP 服务都会执行确认工作流：

• 预览步骤： 当您请求创建或删除操作（例如创建租户或删除 EPG）时，服务会先显示将要推送或删除内容的预览，其中包括对象的完整负载或可分辨名称（DN）。
• 需要明确确认： 只有在您明确确认后（例如回复“是”或在界面中确认），操作才会继续。如果您未确认，操作将取消，不会进行任何更改。
• 安全性： 此工作流有助于防止意外更改，并确保您有机会在执行任何具有破坏性或影响重大的操作前进行检查。

示例：创建租户

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

示例：删除租户

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

此确认工作流适用于 MCP 服务提供的所有创建和删除操作。

---

🚀 开始使用

前提条件

• 为获得最佳兼容性，请使用 Python 3.12+
• 可访问 Cisco APIC 控制器
• 可连接到 APIC 管理接口的网络
• VS Code（用于 VS Code 集成）或 Claude Desktop（用于 Claude 集成）

安装

1. 克隆仓库

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

2. 安装依赖项

# Install all dependencies
pip install -r requirements.txt

requirements.txt 包含：

• fastmcp（核心 MCP 服务框架）
• requests（HTTP 客户端）
• python-dotenv（环境变量管理）
• beautifulsoup4（HTML 解析）
• python-docx（Word 文档生成）
• uvicorn（可选，异步服务）

pytest、flake8（可选，用于测试/代码检查）

3. 配置环境

# 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

编辑 .env 文件，填写您的 APIC 详细信息：

# 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 客户端配置

选项 1：VS Code 集成

1. 安装 MCP 扩展

   • 在 VS Code 中安装“Model Context Protocol”扩展
   • 或安装支持 MCP 的“Claude Dev”扩展

2. 配置 MCP 服务

   创建或更新 VS Code 的 .vscode/mcp.json：

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

将 <path-to-your-apic_mcp_server.py> 替换为 apic_mcp_server.py 文件的完整路径。

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. 添加 MCP 服务配置

   编辑 claude_desktop_config.json：

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

将 <full-path-to-your-apic_mcp_server.py> 替换为 apic_mcp_server.py 文件的完整路径。 如果项目路径遇到问题，您可能需要相应地调整路径，例如：

 {
   "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>"
       ]
     }
   }
 }

将 <full-path-to-your-uv> 替换为 uv 可执行文件的完整路径，并将 <full-path-to-your-apic_mcp_server> 替换为包含 apic_mcp_server.py 的目录。

3. 重启 Claude Desktop，即可在对话中使用 APIC 工具。

🧪 测试设置

1. 测试环境变量

# 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. 测试 MCP 服务

# 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. 测试 APIC 连通性

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

🎯 使用 APIC-MCP 服务

在 VS Code 或 Claude Desktop 中完成配置后，您可以使用自然语言与 ACI fabric 交互：

在 VS Code 中使用 MCP 扩展：

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'"

在 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"

💡 使用示例

基本租户分析

# 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")

安全监控

# 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)")

文档生成

# 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"
)

🔧 开发指南

项目结构

<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

添加新工具

1. 定义工具函数

@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. 添加错误处理

• 始终检查身份验证状态
• 对 API 调用使用 try-catch 语句块
• 返回一致的响应格式
• 适当地记录错误

3. 编写工具文档

• 添加清晰的文档字符串
• 包含参数说明
• 提供使用示例
• 更新此 README

代码风格指南

• 符合 PEP 8：遵循 Python 编码标准
• 类型提示：为所有函数使用类型注解
• 错误处理：实施全面的错误处理
• 文档：为所有函数和类编写文档
• 日志记录：使用适当的日志级别

测试

# 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())
"

🐛 故障排除

常见问题

1. 身份验证失败

Error: "Authentication failed: Invalid credentials"

解决方案：

• 确认 APIC URL 正确且可访问
• 检查 .env 文件中的用户名和密码
• 确保 APIC 证书受信任（测试时设置 VERIFY_SSL=false）
• 检查与 APIC 管理界面的网络连接

2. SSL 证书问题

Error: "SSL: CERTIFICATE_VERIFY_FAILED"

解决方案：

# Temporary fix for testing
export PYTHONHTTPSVERIFY=0

# Or set in .env
APIC_VERIFY_SSL=false

3. 模块导入错误

Error: "ModuleNotFoundError: No module named 'mcp'"

解决方案：

# 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 超时

Error: "Request timeout"

解决方案：

• 检查与 APIC 的网络延迟
• 确认 APIC 未过载
• 在 auth_utils.py 中增加超时时间
• 检查防火墙规则

5. 权限被拒绝

Error: "Insufficient privileges"

解决方案：

• 确认用户拥有适当的 APIC 权限
• 检查用户角色分配
• 使用管理员账户进行测试
• 检查 RBAC 策略

调试模式

启用调试日志：

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

环境验证

# 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

性能调优

• 连接池：重复使用 APIC 会话
• 缓存：缓存经常访问的数据
• 分页：对大型数据集使用分页
• 筛选：尽可能使用服务端筛选

日志和监控

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

🤝 参与贡献

如何贡献

1. Fork 仓库
2. 创建描述性名称的功能分支

   git checkout -b feature/new-feature
   

3. 进行更改
   • 遵循代码风格指南
   • 添加全面的测试
   • 更新文档
4. 提交更改

   git commit -m "Add new feature"
   

5. 推送到分支

   git push origin feature/new-feature
   

6. 发起 Pull Request

开发环境设置

# 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

可参与贡献的领域

• 新的 APIC 工具：添加对更多 APIC 类 / 用例的支持
• 增强分析：改进 fabric 对象分析算法
• 文档：改进示例和教程
• 测试：添加全面的测试套件
• 性能：优化 API 调用和缓存

📝 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🆘 支持

• 问题：GitHub Issues
• 文档：此 README 和内联代码注释

🔗 相关资源

• Cisco ACI 文档
• MCP 协议规范
• FastMCP 框架
• Cisco PSIRT API

---

为网络自动化和 ACI 管理倾情打造 ❤️