使用说明

认证

始终使用来自的凭据执行对APIC的身份验证 .env 文件。这 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服务器

用于管理和分析Cisco ACI（以应用程序为中心的基础设施）结构的综合模型上下文协议（MCP）服务器。此工具为网络管理员和开发人员提供了一个强大的界面，用于与Cisco APIC控制器交互、执行分析和生成详细报告。

🚀 什么是APIC MCP服务器？

APIC MCP服务器是一个基于Python的MCP服务器，它提供：

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

🏗️ 架构概述

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   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. .vcode/ （VS代码集成）

MCP配置：VS代码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() -注销和清理会话

面料发现

get_tenants() -列出所有租户
get_fabric_nodes() -列出结构交换机和控制器
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() -在结构中创建APIC对象
delete_apic_object() -从结构中删除APIC对象

警告： 这些工具直接在您的Cisco ACI结构上执行更改。创建或删除对象可能会中断生产环境、导致中断或导致数据丢失。始终仔细检查您的参数，只有在了解影响的情况下才能使用这些工具。建议先在非生产环境中进行测试。

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

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

预览步骤： 当您请求创建或删除操作（例如，创建租户或删除EPG）时，服务器将首先向您显示将被推送或删除的内容的预览。这包括对象的完整有效载荷或可分辨名称（DN）。
需要明确确认： 只有您明确确认（例如，通过回答“是”或在UI中确认），操作才会继续。如果不确认，操作将被取消，不会进行任何更改。
安全： 此工作流程有助于防止意外更改，并确保您有机会在执行所有破坏性或有影响的操作之前对其进行审查。

示例：创建租户

# 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集成）

安装

克隆存储库

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

再进行

# Install all dependencies
pip install -r requirements.txt

这 requirements.txt 包括：

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

pytest，flake8（可选，用于测试/剥皮）

配置环境

# 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代码集成

安装MCP扩展
- 在VS代码中安装“模型上下文协议”扩展
- 或者安装支持MCP的“Claude Dev”扩展

配置MCP服务器

创建或更新您的VS代码 .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

添加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.

重新启动克劳德桌面 APIC工具将在您的对话中提供。

🧪 测试您的设置

测试环境变量

# 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

测试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')
"

测试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结构进行交互：

在带有MCP扩展的VS代码中：

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

在克劳德桌面中：

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

添加新工具

定义工具功能

@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)}"
        }

添加错误处理

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

记录工具

添加清晰的文档字符串
包括参数说明
提供使用示例
更新此自述文件

代码风格指南

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

🤝 贡献

如何做出贡献

分叉存储库
使用描述性名称创建要素分支
```
git checkout -b feature/new-feature
```
进行更改
- 遵循代码风格指南
- 添加综合测试
- 更新文档
提交更改
```
git commit -m "Add new feature"
```
推送到分支
```
git push origin feature/new-feature
```
打开拉取请求

开发设置

# 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类/用例的支持
增强分析：改进结构对象分析算法
文档：改进示例和教程
测试：添加全面的测试套件
演出：优化API调用和缓存

📝 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

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

🔗 相关资源

由以下材料制成❤️ 用于网络自动化和ACI管理

使用说明

认证

APIC MCP服务器

🚀 什么是APIC MCP服务器？

🏗️ 架构概述

📦 组件

核心组件

1. apic_mcp_server.py （主服务器）

2. auth_utils.py （身份验证）

配置文件

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

4. .vcode/ （VS代码集成）

🛠️ 可用工具

身份验证和状态

面料发现

租户管理

证券分析

外部连接

安全情报

文档

⚠️ 危险作业

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

示例：创建租户

示例：删除租户

🚀 入门指南

先决条件

安装

pytest，flake8（可选，用于测试/剥皮）

🔧 MCP客户端配置

选项1:VS代码集成

🧪 测试您的设置

🎯 使用APIC-MCP服务器

在带有MCP扩展的VS代码中：

在克劳德桌面中：

💡 使用示例

租户基本分析

安全监控

文档生成

🔧 开发指南

项目结构

添加新工具

代码风格指南

测试

🐛 故障排除

常见问题

1. 身份验证失败

2. SSL证书问题

3. 模块导入错误

4. APIC API超时

5. 权限不足

调试模式

环境验证

性能调整

日志和监控

🤝 贡献

如何做出贡献

开发设置

贡献领域

📝 许可证

🆘 支持

🔗 相关资源

相关 MCP

网络控制协议服务器

UniFi MCP服务器

网络工程师MCP工具

OpenWRT路由器管理MCP服务器

网络管理容器套件

Cisco设备管理服务器