Cisco Aci Mcp Server

認証

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-Server

Cisco ACI（Application Centric Infrastructure）ファブリックを管理、分析するための包括的な Model Context Protocol（MCP）サーバーです。このツールは、ネットワーク管理者や開発者が Cisco APIC コントローラーを操作し、分析を実行して、詳細なレポートを作成するための強力なインターフェースを提供します。

🚀 APIC-MCP-Server とは？

APIC-MCP-Server は 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. .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() - ログアウトしてセッションをクリーンアップ

ファブリックの検出

• 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）が含まれます。
• 明示的な確認が必要： 明示的に確認（「yes」と返信するか、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 統合には Claude Desktop

インストール

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 ファブリックを操作できます。

MCP 拡張機能を使用した VS Code の場合：

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. ツールをドキュメント化する

• 分かりやすい docstring を追加する
• パラメーターの説明を含める
• 使用例を提示する
• この 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. リポジトリをフォークする
2. 説明的な名前のフィーチャーブランチを作成する

   git checkout -b feature/new-feature
   

3. 変更を加える
   • コードスタイルのガイドラインに従います
   • 包括的なテストを追加します
   • ドキュメントを更新します
4. 変更をコミットする

   git commit -m "Add new feature"
   

5. ブランチにプッシュする

   git push origin feature/new-feature
   

6. プルリクエストを作成する

開発環境のセットアップ

# 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 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。

🆘 サポート

• 問題：GitHub Issues
• ドキュメント：この README とコード内のコメント

🔗 関連リソース

• Cisco ACI ドキュメント
• MCP Protocol Specification
• FastMCP Framework
• Cisco PSIRT API

---

ネットワーク自動化と ACI 管理のために ❤️ を込めて作成