ISE MCP 서버(FastMCP 사용)

개요

ISE MCP 서버는 Python fastmcp 라이브러리로 구축된 모델 컨텍스트 프로토콜(MCP) 서버입니다. Cisco Identity Services Engine(ISE) API 엔드포인트를 구조화되고 검색 가능한 MCP 도구로 동적으로 노출합니다. 이 서버를 통해 클라이언트는 표준화된 방식으로 Cisco ISE REST API와 상호 작용할 수 있으며, 동적 도구 생성 및 API 응답 필터링과 같은 기능을 제공합니다.

Related MCP server: Salesforce MCP Integration

특징

• 동적 도구 생성: MCP 도구는 src/ise_mcp_server/urls.json 구성 파일의 항목을 기반으로 자동으로 생성됩니다.

• FastMCP 통합: 스키마 생성 및 요청 처리를 포함하여 강력한 MCP 서버 구현을 위해 fastmcp 라이브러리를 활용합니다.

• 비동기 API 호출: Cisco ISE와의 비차단 통신을 위해 httpx.AsyncClient 사용합니다.

• API 필터링: 각 도구의 filter_expression 및 query_params 인수를 통해 Cisco ISE API 결과 필터링을 지원합니다.

• 환경 기반 구성: Cisco ISE 연결 세부 정보(기본 URL, 사용자 이름, 비밀번호) 및 SSL 확인 설정( ISE_VERIFY_SSL )은 .env 파일을 통해 구성됩니다.

• 자세한 Docstring: 동적으로 생성되는 도구에는 도구의 목적, 대상 ISE API 엔드포인트, 필터링 매개변수 사용 방법 등을 설명하는 포괄적인 docstring이 포함되어 있습니다.

• 표준화된 상호작용: 모델 컨텍스트 프로토콜을 준수하여 모든 MCP 호환 클라이언트를 통한 상호작용이 가능합니다.

• 스트리밍 가능한 HTTP 전송: 웹 기반 액세스를 위해 기본적으로 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 (프로젝트 루트)에 나열되어 있습니다. 다음을 사용하여 설치하세요.

  지엑스피1

  또는 uv 사용하는 경우:

  uv pip install -r requirements.txt

  주요 종속성으로는 fastmcp , httpx , pydantic , python-dotenv 있습니다. ( requirements.txt 에 requests 대신 httpx 반영되도록 하세요.)

구성

1. 환경 변수: Cisco ISE API 자격 증명과 기본 URL을 사용하여 프로젝트 루트 디렉토리( /Users/username/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 구성( 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로 서버 실행

이 서버는 특히 STDIO를 통해 상호 작용하는 Claude Desktop과 같은 클라이언트와 함께 사용할 때 Docker 컨테이너로 실행되도록 설계되었습니다.

필수 조건

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 이미지를 빌드합니다.

또는 프로젝트 루트에서 빌드하는 경우:

Claude Desktop 구성

다음과 같이 "ISE_MCP" 서버에 대한 Claude Desktop MCP 서버 구성( claude_desktop_config.json 또는 cline_mcp_settings.json )을 업데이트하세요.

Docker 인수에 대한 설명:

• run : Docker 컨테이너를 실행합니다.

• -i : (대화형) STDIO 기반 MCP 통신에 중요한, 연결되어 있지 않더라도 STDIN을 열어 둡니다.

• --rm : 컨테이너가 종료될 때 자동으로 제거합니다.

• --env-file : 호스트 머신의 .env 파일 경로를 지정합니다. Docker는 이 변수들을 컨테이너에 로드합니다.

• ise-mcp:latest : 실행할 Docker 이미지의 이름과 태그입니다.

• cwd : 명령에 대한 작업 디렉터리를 설정하여 Claude Desktop이 다른 기본 디렉터리에서 명령을 실행하는 경우 상대 경로(예: --env-file )가 올바르게 확인되도록 합니다.

Docker Compose로 실행(로컬 테스트 대안)

로컬 테스트를 위해 docker-compose.yml 파일도 제공됩니다. 이미지를 빌드하고 컨테이너를 실행하며, .env 파일에서 환경 변수를 로드합니다.

이 방법은 직접 테스트에 적합하지만 Claude Desktop 통합을 위해서는 위의 docker run 구성이 더 선호됩니다.

로컬에서 서버 실행(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 검사관과 함께 지역 개발을 위해:

이 명령을 실행하면 MCP 검사기가 시작됩니다.

• 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. uv 환경에 설치된 fastmcp (전역적으로) 사용될 것입니다.

3. 프로젝트 루트에 .env 파일이 있습니다.

실행:

이 명령은 uv 지정된 프로젝트 디렉터리에서 fastmcp run src/ise_mcp_server/server.py --transport stdio 실행하도록 지시합니다. --transport stdio 플래그는 STDIO를 기대하는 클라이언트에게 중요합니다.

uv Claude Desktop에 이 방법을 선호하는 경우 다음과 같이 구성할 수 있습니다.

서버 이름을 "ISE_LOCAL_UV"로 지정하거나 키를 적절히 조정하면 Claude Desktop에서 이 구성을 선택합니다. fastmcp run 은 현재 작업 디렉터리(이 경우 /Users/username/mcp_servers/ISE_MCP )에서 .env 파일을 자동으로 로드합니다.

서버와 상호 작용

ISE MCP 서버를 실행하면 모든 MCP 호환 클라이언트(예: MCP Inspector)를 사용하여 액세스할 수 있습니다.

도구 발견

클라이언트는 사용 가능한 도구를 찾을 수 있습니다. 각 도구는 urls.json 파일의 항목에 해당합니다. 도구 이름은 Name 필드에서 파생됩니다(예: "Identity Groups"는 identity_groups 가 됩니다).

도구 호출

도구는 단일 선택 인수인 params 를 통해 호출됩니다. params는 Pydantic 모델( FilterableToolInput 또는 NonFilterableToolInput )의 인스턴스입니다.

예: 필터 없이 MCP 클라이언트는 일반적으로 도구의 입력 모델이 default_factory 사용하는 경우 명시적 인수 없이 도구를 호출하는 것을 허용합니다.

예: 필터를 사용하여 인수는 Pydantic 모델에 따라 구성됩니다. FilterableFields 를 사용하여 엔드포인트에서 생성된 도구의 경우:

• filter_expression (문자열, 선택 사항): fieldName.OPERATION.value 형식(예: mac.EQUALS.AA:BB:CC:DD:EE:FF )으로 필터를 지정합니다. 사용 가능한 FilterableFields 및 지원되는 ISE 작업(예: CONTAINS, EQUALS, STARTSWITH)은 도구의 docstring을 참조하세요.

• query_params (dict, 선택 사항): 다른 임의의 쿼리 매개변수(예: {"size": 100, "page": 2} )를 지정할 수 있습니다. 이러한 매개변수는 ISE API에 직접 전달됩니다.

urls.json 의 엔드포인트에 빈 FilterableFields 배열이 있는 경우 해당 도구는 query_params 만 허용합니다.

각 도구의 동적으로 생성된 docstring을 참조하여 엔드포인트와 사용 가능한 필터링 필드에 대한 구체적인 세부 정보를 확인하세요.

벌채 반출

서버는 fastmcp 로 구성된 표준 Python logging 모듈을 사용합니다. 서버 작업 및 API 상호작용과 관련된 로그 메시지가 콘솔에 출력됩니다.

특허

아파치 2.0 라이선스