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 响应等功能。

功能

• 动态生成工具： 根据 src/ise_mcp_server/urls.json 配置文件中的条目自动创建 MCP 工具。
• FastMCP 集成： 利用 fastmcp 库实现稳健的 MCP 服务，包括架构生成和请求处理。
• 异步 API 调用： 使用 httpx.AsyncClient 与 Cisco ISE 进行非阻塞通信。
• API 筛选： 支持通过每个工具中的 filter_expression 和 query_params 参数筛选 Cisco ISE API 结果。
• 环境驱动的配置： 通过 .env 文件配置 Cisco ISE 连接详情（基础 URL、用户名、密码）和 SSL 验证设置（ISE_VERIFY_SSL）。
• 详细的文档字符串： 动态生成的工具包含全面的文档字符串，说明工具用途、目标 ISE API 端点以及筛选参数的使用方法。
• 标准化交互： 遵循 Model Context Protocol，可通过任何兼容 MCP 的客户端进行交互。
• 可流式传输的 HTTP 传输： 默认配置为使用 streamable-http 传输，以便通过 Web 访问。

设置

服务

{ "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 中使用的是 httpx，而非 requests。）

配置

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" 可禁用验证（不安全）。
   # 或者提供 CA 证书包文件的路径，例如 "/path/to/your/ca.pem"。
   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"]
     }
     // ... 更多端点
   ]
   

   • URL：Cisco ISE API 端点的相对路径。
   • Name：用于生成 MCP 工具名称的易读名称（例如，“Endpoints”会生成工具 endpoints）。
   • FilterableFields：字符串数组，列出此端点可用于 filter_expression 的已知字段。此列表由用户维护，对有效筛选至关重要。

使用 Docker 为 Claude Desktop 运行服务

此服务设计为在 Docker 容器中运行，尤其适用于通过 STDIO 进行交互的 Claude Desktop 等客户端。

前提条件

1. 已安装 Docker： 确保已安装并运行 Docker Desktop。
2. .env 文件： 项目根目录（/Users/username/mcp_servers/ISE_MCP/.env）中必须存在 .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

按如下所示，更新 Claude Desktop 的 MCP 服务配置（claude_desktop_config.json 或 cline_mcp_settings.json）中的 “ISE_MCP” 服务：

{
  "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：设置命令的工作目录，确保相对路径（例如 --env-file 的路径）在 Claude Desktop 从其他默认目录运行命令时也能正确解析。

使用 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. fastmcp 已安装在 uv 将使用的环境中（或全局安装）。
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 会自动从当前工作目录加载 .env 文件（此处为 /Users/username/mcp_servers/ISE_MCP）。

与服务交互

启动后，可使用任何兼容 MCP 的客户端（例如 MCP Inspector）访问 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）请参阅工具的文档字符串。
• query_params（字典，可选）：用于指定其他任意查询参数（例如，{"size": 100, "page": 2}）。这些参数会直接传递给 ISE API。

如果 urls.json 中某个端点的 FilterableFields 数组为空，则对应的工具仅接受 query_params。

有关端点及可用筛选字段的具体信息，请参阅每个工具动态生成的文档字符串。

日志记录

服务器使用由 fastmcp 配置的标准 Python logging 模块。与服务器操作和 API 交互相关的日志消息将输出到控制台。

许可证

Apache 2.0 许可证