ISE MCP Server

# ISE MCP Server (using FastMCP) ## Overview The ISE MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server built with the Python [`fastmcp`](https://gofastmcp.com/) library. It dynamically exposes Cisco Identity Services Engine (ISE) API endpoints as structured, discoverable MCP tools. This server allows clients to interact with Cisco ISE REST APIs in a standardized way, offering features like dynamic tool generation and API response filtering. ## Features - **Dynamic Tool Generation:** MCP tools are automatically created based on entries in the `src/ise_mcp_server/urls.json` configuration file. - **FastMCP Integration:** Leverages the `fastmcp` library for robust MCP server implementation, including schema generation and request handling. - **Asynchronous API Calls:** Uses `httpx.AsyncClient` for non-blocking communication with Cisco ISE. - **API Filtering:** Supports filtering of Cisco ISE API results through `filter_expression` and `query_params` arguments in each tool. - **Environment-Driven Configuration:** Cisco ISE connection details (base URL, username, password) and SSL verification settings (`ISE_VERIFY_SSL`) are configured via a `.env` file. - **Detailed Docstrings:** Dynamically generated tools include comprehensive docstrings explaining their purpose, the ISE API endpoint they target, and how to use filtering parameters. - **Standardized Interaction:** Adheres to the Model Context Protocol, allowing interaction via any MCP-compatible client. - **Streamable HTTP Transport:** Configured to use `streamable-http` transport by default for web-based access. ## Setup ## Server { "mcpServers": { "ise": { "command": "python", "args": [ "ise_mcp_server.py", "--oneshot" ], "env": { "ISE_BASE": "https://devnetsandboxise.cisco.com", "USERNAME": "readonly", "PASSWORD": "ISEisC00L" } } } } ### Requirements - Python 3.9 or higher. - Required Python packages are listed in `requirements.txt` (at the project root). Install them using: ```bash pip install -r requirements.txt ``` Or, if using `uv`: ```bash uv pip install -r requirements.txt ``` Key dependencies include `fastmcp`, `httpx`, `pydantic`, and `python-dotenv`. (Ensure `requirements.txt` reflects `httpx` instead of `requests`). ### Configuration 1. **Environment Variables:** Create a `.env` file in the project root directory (`/Users/username/mcp_servers/ISE_MCP/.env`) with your Cisco ISE API credentials and base URL: ```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 Configuration (`urls.json`):** Ensure the `src/ise_mcp_server/urls.json` file (located in the same directory as `src/ise_mcp_server/server.py`) is present and structured correctly. This file defines the ISE API endpoints that will be exposed as MCP tools. ```json [ { "URL": "/ers/config/endpoint", "Name": "Endpoints", "FilterableFields": ["mac", "name", "description", "identityGroupName"] }, { "URL": "/ers/config/identitygroup", "Name": "Identity Groups", "FilterableFields": ["name", "description"] } // ... more endpoints ] ``` - `URL`: The relative path of the Cisco ISE API endpoint. - `Name`: A human-readable name used to derive the MCP tool name (e.g., "Endpoints" becomes the tool `endpoints`). - `FilterableFields`: An array of strings listing known fields that can be used with the `filter_expression` for this endpoint. This list is user-maintained and crucial for effective filtering. ## Running the Server with Docker for Claude Desktop This server is designed to be run as a Docker container, especially when used with clients like Claude Desktop that interact via STDIO. ### Prerequisites 1. **Docker Installed:** Ensure Docker Desktop is installed and running. 2. **`.env` File:** Your `.env` file (as described in Configuration) must be present in the project root (`/Users/username/mcp_servers/ISE_MCP/.env`). 3. **Dockerfile Configured for STDIO:** The `Dockerfile` in this project (`Dockerfile`) should be configured to use `stdio` transport. The `ENTRYPOINT` should look like: ```dockerfile ENTRYPOINT ["python", "-m", "ise_mcp_server", "--transport", "stdio"] ``` Ensure it does *not* copy the `.env` file. ### Build the Docker Image Navigate to the directory containing the Dockerfile (`/Users/username/mcp_servers/ISE_MCP/`) and build the Docker image: ```bash docker build -t ise-mcp:latest . ``` Alternatively, if building from the project root: ```bash docker build -t ise-mcp:latest -f src/Dockerfile . ``` ### Configure Claude Desktop Update your Claude Desktop MCP server configuration (`claude_desktop_config.json` or `cline_mcp_settings.json`) for the "ISE_MCP" server as follows: ```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 ... } } ``` **Explanation of Docker arguments:** - `run`: Executes the Docker container. - `-i`: (Interactive) Keeps STDIN open even if not attached, crucial for STDIO-based MCP communication. - `--rm`: Automatically removes the container when it exits. - `--env-file`: Specifies the path to your `.env` file on your host machine. Docker will load these variables into the container. - `ise-mcp:latest`: The name and tag of the Docker image to run. - `cwd`: Sets the working directory for the command, ensuring that relative paths (like for `--env-file`) are resolved correctly if Claude Desktop runs commands from a different default directory. ### Running with Docker Compose (Alternative for local testing) A `docker-compose.yml` file is also provided for local testing. It builds the image and runs the container, loading environment variables from the `.env` file. ```bash docker-compose up --build ``` This method is suitable for direct testing but the `docker run` configuration above is preferred for Claude Desktop integration. ## Running the Server Locally (without Docker) For development or when Docker is not preferred, you can run the server directly using Python. ### Prerequisites 1. **Python Environment:** Ensure you have Python 3.9+ and have installed the dependencies from `requirements.txt`. 2. **`.env` File:** The `.env` file must be present in the project root (`/Users/username/mcp_servers/ISE_MCP/.env`). ### Execution Navigate to the project root directory and run: ```bash python src/ise_mcp_server/server.py ``` By default, `src/ise_mcp_server/server.py` is configured to start the server using `streamable-http` transport, typically available at `http://127.0.0.1:8000/mcp`. You can modify `server.py` to change the transport (e.g., to `stdio`) or other server parameters if needed for your specific client. ### Development and Testing with MCP Inspector (Local Python) For local development with the MCP Inspector: ```bash python -m fastmcp dev src/ise_mcp_server/server.py --with httpx --with pydantic --with python-dotenv ``` After running this command, the MCP Inspector will launch. - **For STDIO testing with Inspector:** 1. Select "STDIO" as the transport type in the Inspector. 2. Set the command to run the server as `python src/ise_mcp_server/server.py`. 3. Connect to the server. - **For HTTP testing with Inspector:** 1. Run `python src/ise_mcp_server/server.py` in a separate terminal to start the server (it will use `streamable-http` by default). 2. In the MCP Inspector, select "HTTP". 3. Set the URL to `http://127.0.0.1:8000/mcp` (or your configured endpoint). 4. Connect to the server. ### Running Locally with `uv` and `fastmcp run` (Alternative for STDIO) If you have `uv` and `fastmcp` installed globally or in your environment, you can also run the server using the `fastmcp run` command, which is often useful for STDIO-based clients. **Prerequisites:** 1. `uv` installed and in your PATH. 2. `fastmcp` installed in the environment `uv` will use (or globally). 3. `.env` file present in the project root. **Execution:** ```bash uv --directory /Users/username/mcp_servers/ISE_MCP run fastmcp run src/ise_mcp_server/server.py --transport stdio ``` This command tells `uv` to execute `fastmcp run src/ise_mcp_server/server.py --transport stdio` within the specified project directory. The `--transport stdio` flag is important for clients expecting STDIO. **Claude Desktop Configuration for `uv` method:** If you prefer this method for Claude Desktop, you can configure it as follows: ```json { "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 ... } } ``` This configuration will be picked up by Claude Desktop if you name your server "ISE_LOCAL_UV" or adjust the key accordingly. Note that `fastmcp run` will automatically load the `.env` file from the current working directory (`/Users/username/mcp_servers/ISE_MCP` in this case). ## Interacting with the Server Once running, the ISE MCP Server can be accessed using any MCP-compatible client (e.g., MCP Inspector). ### Tool Discovery Clients can discover available tools. Each tool corresponds to an entry in `urls.json`. Tool names are derived from the `Name` field (e.g., "Identity Groups" becomes `identity_groups`). ### Calling a Tool Tools are called with a single optional argument, `params`, which is an instance of a Pydantic model (`FilterableToolInput` or `NonFilterableToolInput`). **Example: Calling the `endpoints` tool without filters:** An MCP client would typically allow calling the tool without explicit arguments if the tool's input model uses `default_factory`. **Example: Calling the `endpoints` tool with filters:** The arguments would be structured according to the Pydantic model. For a tool generated from an endpoint with `FilterableFields`: ```json // Example arguments for a tool call (client-dependent format) { "params": { "filter_expression": "name.CONTAINS.mydevice", "query_params": { "size": 10, "page": 1 } } } ``` - `filter_expression` (string, optional): Specifies filters in the format `fieldName.OPERATION.value` (e.g., `mac.EQUALS.AA:BB:CC:DD:EE:FF`). Refer to the tool's docstring for available `FilterableFields` and supported ISE operations (e.g., CONTAINS, EQUALS, STARTSWITH). - `query_params` (dict, optional): Allows specifying other arbitrary query parameters (e.g., `{"size": 100, "page": 2}`). These are passed directly to the ISE API. If an endpoint in `urls.json` has an empty `FilterableFields` array, the corresponding tool will only accept `query_params`. Refer to the dynamically generated docstring of each tool for specific details on its endpoint and available filterable fields. ## Logging The server uses the standard Python `logging` module, configured by `fastmcp`. Log messages related to server operations and API interactions will be output to the console. ## License Apache 2.0 License