ISE MCP Server

ISE MCP 服务器（使用 FastMCP）

概述

ISE MCP 服务器是一个使用 Python fastmcp库构建的模型上下文协议 (MCP)服务器。它动态地将思科身份服务引擎 (ISE) API 终端公开为结构化、可发现的 MCP 工具。该服务器允许客户端以标准化方式与思科 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文件配置。
• **详细的文档字符串：**动态生成的工具包括全面的文档字符串，解释其用途、其目标的 ISE API 端点以及如何使用过滤参数。
• **标准化交互：**遵守模型上下文协议，允许通过任何兼容 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. **环境变量：**使用您的 Cisco ISE API 凭证和基本 URL 在项目根目录（ /Users/username/mcp_servers/ISE_MCP/.env mcp_servers/ISE_MCP/.env ）中创建一个.env文件：
   ISE_BASE="https://your-ise-instance.example.com" USERNAME="your-ise-api-username" PASSWORD="your-ise-api-password" # Optional: Controls SSL certificate verification for ISE API calls. # Default is true. Set to "false" to disable (insecure). # Or provide a path to a CA bundle file, e.g., "/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"] } // ... more endpoints ]
   • URL ：Cisco ISE API 端点的相对路径。
   • Name ：用于派生 MCP 工具名称的人性化名称（例如，“端点”成为工具endpoints ）。
   • FilterableFields ：一个字符串数组，列出了可与此端点的filter_expression一起使用的已知字段。此列表由用户维护，对于有效过滤至关重要。

使用 Docker 为 Claude Desktop 运行服务器

该服务器设计为作为 Docker 容器运行，尤其是与通过 STDIO 交互的 Claude Desktop 等客户端一起使用时。

先决条件

1. **Docker 已安装：**确保 Docker Desktop 已安装并正在运行。
2. **.env文件：**您的.env文件（如配置中所述）必须存在于项目根目录（ /Users/username/mcp_servers/ISE_MCP/.env mcp_servers/ISE_MCP/.env ）中。
3. **已配置 Dockerfile 的 STDIO：**本项目中的Dockerfile ( Dockerfile ) 应配置为使用stdio传输ENTRYPOINT应如下所示：
   ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"]
   确保它不会复制.env文件。

构建 Docker 镜像

导航到包含 Dockerfile ( /Users/username/mcp_servers/ISE_MCP/ ) 的目录并构建 Docker 映像：

或者，如果从项目根目录构建：

配置 Claude 桌面

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

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 run配置更适合 Claude Desktop 集成。

本地运行服务器（不使用 Docker）

对于开发或当不喜欢 Docker 时，您可以直接使用 Python 运行服务器。

先决条件

1. **Python 环境：**确保您拥有 Python 3.9+ 并且已从requirements.txt安装了依赖项。
2. .env文件： .env文件必须存在于项目根目录中（ /Users/username/mcp_servers/ISE_MCP/.env ）。

执行

导航到项目根目录并运行：

默认情况下， src/ise_mcp_server/server.py配置为使用streamable-http传输方式启动服务器，通常访问http://127.0.0.1:8000/mcp 。您可以根据特定客户端的需要，修改server.py以更改传输方式（例如，更改为stdio ）或其他服务器参数。

使用 MCP Inspector (本地 Python) 进行开发和测试

对于使用 MCP Inspector 进行本地开发：

运行此命令后，MCP Inspector 将启动。

• 使用 Inspector 进行 STDIO 测试：
  1. 在检查器中选择“STDIO”作为传输类型。
  2. 将运行服务器的命令设置为python src/ise_mcp_server/server.py 。
  3. 连接到服务器。
• 使用 Inspector 进行 HTTP 测试：
  1. 在单独的终端中运行python src/ise_mcp_server/server.py来启动服务器（默认情况下它将使用streamable-http ）。
  2. 在 MCP 检查器中，选择“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在指定的项目目录中执行fastmcp run src/ise_mcp_server/server.py --transport stdio 。 --transport stdio标志对于需要 STDIO 的客户端非常重要。

**Claude Desktop uv方法配置：**如果您更喜欢 Claude Desktop 的这种方法，您可以按如下方式进行配置：

如果您将服务器命名为“ISE_LOCAL_UV”或相应地调整密钥，Claude Desktop 将获取此配置。请注意， fastmcp run将自动从当前工作目录（在本例中/Users/username/mcp_servers/ISE_MCP ）加载.env文件。

与服务器交互

一旦运行，就可以使用任何与 MCP 兼容的客户端（例如 MCP Inspector）访问 ISE MCP 服务器。

工具发现

客户端可以发现可用的工具。每个工具对应urls.json中的一个条目。工具名称源自Name字段（例如，“Identity Groups” 变为identity_groups ）。

调用工具

使用单个可选参数params调用工具，该参数是 Pydantic 模型（ FilterableToolInput或NonFilterableToolInput ）的一个实例。

**示例：调用不带过滤器的endpoints工具：**如果工具的输入模型使用default_factory ，则 MCP 客户端通常允许在没有明确参数的情况下调用该工具。

**示例：使用过滤器调用endpoints工具：**参数将根据 Pydantic 模型进行构造。对于从具有FilterableFields的端点生成的工具：

• 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 。

请参阅每个工具的动态生成的文档字符串，了解有关其端点和可用可过滤字段的具体详细信息。

日志记录

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

执照

Apache 2.0许可证