Cisco Ise Mcp Server

ISE MCP サーバー（FastMCP を使用）

概要

ISE MCP サーバーは、Python の fastmcp ライブラリで構築された Model Context Protocol（MCP） サーバーです。Cisco Identity Services Engine（ISE）の API エンドポイントを、構造化された検出可能な MCP ツールとして動的に公開します。このサーバーを使用すると、クライアントは標準化された方法で Cisco ISE REST API を操作でき、ツールの動的生成や API 応答のフィルタリングなどの機能を利用できます。

機能

• ツールの動的生成： MCP ツールは、src/ise_mcp_server/urls.json 構成ファイルのエントリに基づいて自動的に作成されます。
• FastMCP との統合： fastmcp ライブラリを活用し、スキーマ生成やリクエスト処理を含む堅牢な MCP サーバーを実装します。
• 非同期 API 呼び出し： httpx.AsyncClient を使用して、Cisco ISE とノンブロッキングで通信します。
• API フィルタリング： 各ツールの filter_expression および query_params 引数を使用して、Cisco ISE API の結果をフィルタリングできます。
• 環境変数による構成： Cisco ISE の接続情報（ベース URL、ユーザー名、パスワード）と SSL 検証設定（ISE_VERIFY_SSL）は、.env ファイルで構成します。
• 詳細な docstring： 動的に生成されたツールには、その目的、対象となる ISE API エンドポイント、フィルタリングパラメーターの使用方法を説明する詳しい docstring が含まれます。
• 標準化された操作： Model Context Protocol に準拠しているため、MCP 対応クライアントであればどれからでも操作できます。
• ストリーミング可能な HTTP トランスポート： Web 経由でアクセスできるよう、デフォルトで streamable-http トランスポートを使用するよう構成されています。

セットアップ

サーバー

{ "mcpServers": { "ise": { "command": "python", "args": [ "ise_mcp_server.py", "--oneshot" ], "env": { "ISE_BASE": "https://devnetsandboxise.cisco.com", "USERNAME": "readonly", "PASSWORD": "ISEisC00L" } } } }

要件

• Python 3.9 以降。
• 必要な Python パッケージは、プロジェクトのルートにある requirements.txt に記載されています。次のコマンドでインストールしてください。

  pip install -r requirements.txt
  

  uv を使用する場合は、次のコマンドを実行してください。

  uv pip install -r requirements.txt
  

  主な依存関係には、fastmcp、httpx、pydantic、python-dotenv が含まれます。（requirements.txt に requests ではなく httpx が記載されていることを確認してください。）

設定

1. 環境変数： プロジェクトのルートディレクトリ（/Users/username/mcp_servers/ISE_MCP/.env）に .env ファイルを作成し、Cisco ISE API の認証情報とベース URL を設定します：

   ISE_BASE="https://your-ise-instance.example.com"
   USERNAME="your-ise-api-username"
   PASSWORD="your-ise-api-password"
   # オプション：ISE API 呼び出し時の SSL 証明書検証を制御します。
   # デフォルトは true です。"false" に設定すると検証が無効になります（安全ではありません）。
   # または、"/path/to/your/ca.pem" のように CA バンドルファイルへのパスを指定できます。
   ISE_VERIFY_SSL="true"
   

2. URL の設定（urls.json）： src/ise_mcp_server/urls.json ファイル（src/ise_mcp_server/server.py と同じディレクトリにあります）が存在し、正しい形式になっていることを確認します。このファイルでは、MCP ツールとして公開する ISE API エンドポイントを定義します。

   [
     {
       "URL": "/ers/config/endpoint",
       "Name": "Endpoints",
       "FilterableFields": ["mac", "name", "description", "identityGroupName"]
     },
     {
       "URL": "/ers/config/identitygroup",
       "Name": "Identity Groups",
       "FilterableFields": ["name", "description"]
     }
     // ... more endpoints
   ]
   

   • URL：Cisco ISE API エンドポイントの相対パスです。
   • Name：MCP ツール名の生成に使用する、人が読みやすい名前です（例：「Endpoints」はツール endpoints になります）。
   • FilterableFields：このエンドポイントの filter_expression で使用できる、既知のフィールドを列挙した文字列の配列です。このリストはユーザーが管理するもので、効果的なフィルタリングに不可欠です。

Claude Desktop 向けに Docker でサーバーを実行する

このサーバーは Docker コンテナとして実行するように設計されています。特に、STDIO 経由で通信する Claude Desktop などのクライアントでの使用を想定しています。

前提条件

1. Docker のインストール： Docker Desktop がインストールされ、実行中であることを確認します。
2. .env ファイル： 設定で説明した .env ファイルが、プロジェクトのルート（/Users/username/mcp_servers/ISE_MCP/.env）にある必要があります。
3. STDIO 用に Dockerfile を設定： このプロジェクトの Dockerfile（Dockerfile）は、stdio トランスポートを使用するように設定してください。ENTRYPOINT は次のようになります：

   ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"]
   

   .env ファイルがコピーされないようにしてください。

Docker イメージをビルドする

Dockerfile があるディレクトリ（/Users/username/mcp_servers/ISE_MCP/）に移動し、Docker イメージをビルドします：

docker build -t ise-mcp:latest .

または、プロジェクトのルートからビルドする場合：

docker build -t ise-mcp:latest -f src/Dockerfile .

Claude Desktop を設定する

「ISE_MCP」サーバーについて、Claude Desktop の MCP サーバー設定（claude_desktop_config.json または cline_mcp_settings.json）を次のように更新します：

{
  "mcpServers": {
    // ... other servers ...
    "ISE_MCP": {
      "command": "docker",
      "args": [
        "run",
        "-i",         // Essential for STDIO interaction
        "--rm",       // Automatically remove the container when it exits
        "--env-file=/Users/username/mcp_servers/ISE_MCP/.env", // Mounts your .env file
        "ise-mcp:latest" // The image we just built
      ],
      "cwd": "/Users/username/mcp_servers/ISE_MCP" // Ensures paths are correct
    }
    // ... other servers ...
  }
}

Docker 引数の説明：

• run：Docker コンテナを実行します。
• -i：（対話モード）アタッチされていない場合でも STDIN を開いたままにします。STDIO ベースの MCP 通信に不可欠です。
• --rm：コンテナの終了時に自動的に削除します。
• --env-file：ホストマシン上の .env ファイルへのパスを指定します。Docker はこれらの変数をコンテナに読み込みます。
• ise-mcp:latest：実行する Docker イメージの名前とタグです。
• cwd：コマンドの作業ディレクトリを設定します。Claude Desktop が別のデフォルトディレクトリからコマンドを実行する場合でも、相対パス（--env-file など）が正しく解決されるようにします。

Docker Compose で実行する（ローカルテスト向けの代替方法）

ローカルテスト用に docker-compose.yml ファイルも用意されています。イメージをビルドしてコンテナを実行し、.env ファイルから環境変数を読み込みます。

docker-compose up --build

この方法は直接テストするのに適していますが、Claude Desktop との連携には上記の docker run 設定を推奨します。

サーバーをローカルで実行する（Docker を使用しない場合）

開発時や Docker を使用しない場合は、Python でサーバーを直接実行できます。

前提条件

1. Python 環境： Python 3.9 以降がインストールされていることを確認し、requirements.txt の依存関係をインストールしてください。
2. .env ファイル： .env ファイルがプロジェクトのルート（/Users/username/mcp_servers/ISE_MCP/.env）に存在している必要があります。

実行

プロジェクトのルートディレクトリに移動して、次を実行します。

python src/ise_mcp_server/server.py

デフォルトでは、src/ise_mcp_server/server.py は streamable-http トランスポートを使用してサーバーを起動するように設定されており、通常は http://127.0.0.1:8000/mcp で利用できます。特定のクライアントに合わせて必要な場合は、server.py を変更してトランスポート（例：stdio）やその他のサーバーパラメーターを変更できます。

MCP Inspector を使用した開発とテスト（ローカル Python）

MCP Inspector を使ってローカルで開発する場合：

python -m fastmcp dev src/ise_mcp_server/server.py --with httpx --with pydantic --with python-dotenv

このコマンドを実行すると、MCP Inspector が起動します。

• Inspector を使用した STDIO テスト：
  1. Inspector でトランスポートの種類として「STDIO」を選択します。
  2. サーバーを実行するコマンドとして python src/ise_mcp_server/server.py を設定します。
  3. サーバーに接続します。
• Inspector を使用した HTTP テスト：
  1. 別のターミナルで python src/ise_mcp_server/server.py を実行してサーバーを起動します（デフォルトで streamable-http が使用されます）。
  2. MCP Inspector で「HTTP」を選択します。
  3. URL に http://127.0.0.1:8000/mcp（または設定したエンドポイント）を指定します。
  4. サーバーに接続します。

uv と fastmcp run を使用したローカル実行（STDIO の代替方法）

uv と fastmcp がグローバルまたは環境にインストールされている場合は、fastmcp run コマンドを使ってサーバーを実行することもできます。STDIO ベースのクライアントで役立つことがよくあります。

前提条件：

1. uv がインストールされ、PATH に含まれていること。
2. uv が使用する環境（またはグローバル）に fastmcp がインストールされていること。
3. .env ファイルがプロジェクトのルートに存在すること。

実行：

uv --directory /Users/username/mcp_servers/ISE_MCP run fastmcp run src/ise_mcp_server/server.py --transport stdio

このコマンドは、指定されたプロジェクトディレクトリ内で uv に fastmcp run src/ise_mcp_server/server.py --transport stdio を実行させます。STDIO を想定するクライアントでは、--transport stdio フラグが重要です。

uv を使用する方法での Claude Desktop の設定： Claude Desktop でこの方法を使用する場合は、次のように設定できます。

{
  "mcpServers": {
    // ... other servers ...
    "ISE_LOCAL_UV": { // Using a different key to distinguish
      "command": "uv",
      "args": [
        "--directory",
        "/Users/username/mcp_servers/ISE_MCP",
        "run",
        "fastmcp",
        "run",
        "src/ise_mcp_server/server.py",
        "--transport",
        "stdio"
      ],
      "cwd": "/Users/username/mcp_servers/ISE_MCP", // Ensures .env is found if relative paths are used by fastmcp for .env loading
      "transportType": "stdio" // Explicitly tell Claude this is an STDIO server
    }
    // ... other servers ...
  }
}

サーバー名を「ISE_LOCAL_UV」にするか、それに応じてキーを変更すると、この設定が Claude Desktop に読み込まれます。fastmcp run は、現在の作業ディレクトリ（この例では /Users/username/mcp_servers/ISE_MCP）から .env ファイルを自動的に読み込むことに注意してください。

サーバーとのやり取り

起動すると、MCP Inspector など、MCP 互換のクライアントから ISE MCP Server にアクセスできます。

ツールの検出

クライアントは利用可能なツールを検出できます。各ツールは urls.json のエントリーに対応しています。ツール名は Name フィールドから生成されます（例：「Identity Groups」は identity_groups になります）。

ツールの呼び出し

ツールは、単一の省略可能な引数 params を使って呼び出します。この引数は、Pydantic モデル（FilterableToolInput または NonFilterableToolInput）のインスタンスです。

例：フィルターを指定せずに endpoints ツールを呼び出す場合： ツールの入力モデルで default_factory が使われていれば、通常、MCP クライアントでは引数を明示せずにツールを呼び出せます。

例：フィルターを指定して endpoints ツールを呼び出す場合： 引数は、Pydantic モデルに従って構成します。FilterableFields を持つエンドポイントから生成されたツールの場合：

// Example arguments for a tool call (client-dependent format)
{
  "params": {
    "filter_expression": "name.CONTAINS.mydevice",
    "query_params": {
      "size": 10,
      "page": 1
    }
  }
}

• filter_expression（文字列、省略可能）：fieldName.OPERATION.value の形式でフィルターを指定します（例：mac.EQUALS.AA:BB:CC:DD:EE:FF）。利用可能な FilterableFields とサポートされる ISE の操作（例：CONTAINS、EQUALS、STARTSWITH）については、ツールの docstring を参照してください。
• query_params（辞書、省略可能）：その他の任意のクエリパラメーターを指定できます（例：{"size": 100, "page": 2}）。これらは ISE API に直接渡されます。

urls.json のエンドポイントに空の FilterableFields 配列が指定されている場合、対応するツールが受け付けるのは query_params のみです。

エンドポイントと利用可能なフィルターフィールドの詳細については、各ツールの動的に生成される docstring を参照してください。

ロギング

サーバーでは、fastmcp によって設定された標準の Python logging モジュールを使用します。サーバーの操作や API とのやり取りに関するログメッセージは、コンソールに出力されます。

ライセンス

Apache 2.0 ライセンス