ISE MCP Server

ISE MCP 서버(FastMCP 사용)

개요

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

특징

• 동적 도구 생성: 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 구성( 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로 서버 실행

이 서버는 특히 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 구성: 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 )의 인스턴스입니다.

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

예: 필터를 사용하여 endpoints 도구 호출: 인수는 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 라이선스