delinea-mcp Server

공식

Delinea Secret Server 및 Platform API를 위한 공식 Delinea MCP 서버입니다.

GitHub

문서

DelineaMCP

Delinea Secret Server 및 Platform API를 위한 MCP 서버

기능

Secret Server에 대한 자동 인증
폴더, 시크릿, 사용자, 그룹 및 역할 관리를 위한 광범위한 Secret Server 도구 세트. 받은 편지함 및 액세스 요청 도우미와 코딩 에이전트 유틸리티 포함.
제어된 AI 상호 작용을 위한 ChatGPT 호환 도구 (search 및 fetch).
선택적 Delinea Platform 사용자 관리 도구
Server Sent Events 또는 STDIO 전송 모드 지원
MCP 사양에 따른 동적 클라이언트 등록을 포함한 OAuth 2.0
보안 연결을 위한 TLS 지원
즉시 실행 가능한 Docker 이미지 및 개발 서버 진입점
ChatGPT, Claude Desktop, 원격 Claude 커넥터, VSCode Copilot 및 openwebui에서 테스트됨

설치

[!NOTE]

이 프로젝트는 uv (https://github.com/astral-sh/uv)을 사용하지만, 이것 없이 명령을 실행하려면 원하는 경우 평소처럼 pip 및 venv 명령을 수행할 수 있습니다.

Uv 설치
프로젝트 초기화: uv pip sync requirements.txt
uv run server.py --config config.json 사용

구성

비밀번호와 같은 시크릿은 계속 환경 변수에서 가져옵니다. 셸 환경에 DELINEA_PASSWORD을 제공하십시오. 선택적 기능은 AZURE_OPENAI_KEY 또는 PLATFORM_SERVICE_PASSWORD과 같은 추가 변수에 의존합니다.

비밀번호가 아닌 매개변수는 config.json에 속합니다:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

Secret Server Cloud의 경우 /SecretServer 없이 클라우드 URL을 사용하면 됩니다. HTTPS를 활성화하려면 ssl_keyfile 및 ssl_certfile을 지정하십시오. Let's Encrypt의 경우 privkey.pem 및 fullchain.pem 파일을 사용하십시오.

구성 파일은 다음 키를 지원합니다:

delinea_username - Secret Server 사용자 이름. 원하는 작업을 수행할 권한이 있는 프로그래밍 방식 사용자여야 합니다.
delinea_base_url - Secret Server 인스턴스의 기본 URL.
platform_hostname - Platform 테넌트 호스트 이름 (Platform 도구 활성화).
platform_service_account - Platform API에 사용되는 서비스 계정.
platform_tenant_id - Platform API 요청을 위한 테넌트 ID.
azure_openai_endpoint - Azure OpenAI 엔드포인트. 자동 보고서 생성이 필요한 경우에만 설정하십시오 (대부분의 에이전트가 자체 보고서 SQL을 생성할 수 있으므로 필요하지 않으면 활성화하지 마십시오).
azure_openai_deployment - Azure OpenAI의 배포 이름.
auth_mode - 인증 모드 (none 또는 oauth). OAuth는 분명히 stdio 전송에서는 작동하지 않습니다.
transport_mode - 명령줄의 경우 stdio, HTTP/SSE의 경우 sse.
chatgpt_disable_scope_checks - ChatGPT 요청에 대한 범위 유효성 검사를 건너뜁니다. ChatGPT 연결에 문제가 발생하는 경우에만 활성화하십시오.
port - sse 모드에서 HTTP 서버의 포트.
debug - 상세 로깅 활성화.
external_hostname - OAuth 토큰 대상을 구성할 때 사용되는 호스트 이름. HTTP(S) 접두사 또는 포트를 추가하지 마십시오.
ssl_keyfile - HTTPS용 SSL 키 경로. (예: privkey.pem)
ssl_certfile - HTTPS용 SSL 인증서 경로. (예: fullchain.pem)
registration_psk - OAuth 클라이언트를 등록하는 데 필요한 사전 공유 키. OAuth 연결을 승인하려면 브라우저에 이 시크릿을 입력해야 합니다.
jwt_key_path - OAuth 토큰에 사용되는 RSA 키 쌍의 위치. 기본값은 .cache/jwt.json입니다. 존재하지 않으면 자동 생성됩니다.
oauth_db_path - OAuth 데이터베이스 파일 경로. 기본값은 .cache/oauth.db입니다. 존재하지 않으면 자동 생성됩니다.
enabled_tools - 등록할 도구 이름 목록. 빈 목록은 모든 도구를 활성화합니다. 사용 사례 또는 작업별로 도구를 선택적으로 활성화하는 것이 좋습니다. 몇 가지 예는 docs/ 폴더를 참조하십시오.
search_objects - search 도구에 허용되는 객체 유형. 기본값은 ["secret"]이지만 user, folder, group 및 role을 포함할 수 있습니다.
fetch_objects - fetch 도구에 허용되는 객체 유형. 기본값은 ["secret"]이지만 search_objects과 동일한 값을 포함할 수 있습니다.

서버 실행

개발 모드에서 로컬로 서버 시작:

python server.py

시작 시 서버는 베어러 토큰을 요청하고 후속 API 요청을 위해 저장합니다. 이 프로젝트는 Secret Server API와 더 통합되도록 확장될 것입니다.

MCP 도구

서버는 Secret Server와 상호 작용하기 위한 여러 MCP 도구를 노출합니다:

run_report(sql_query, report_name=None) - 임시 보고서 생성 및 실행.
ai_generate_and_run_report(description) - Azure OpenAI를 사용하여 SQL 생성 및 실행. Azure OpenAI 변수가 필요합니다.
list_example_reports() - 샘플 쿼리 및 테이블 정보 나열.
get_secret(id, summary=False) - 시크릿 또는 요약 세부 정보 검색.
get_folder(id) - 폴더 메타데이터 및 하위 항목 가져오기.
search_users(query) - 활성 사용자 검색.
search_secrets(query, lookup=False) - 시크릿 검색 또는 조회.
search_folders(query, lookup=False) - 폴더 검색 또는 조회.
get_secret_environment_variable(secret_id, environment) - 지정된 셸에서 시크릿 자격 증명을 가져오기 위한 스크립트 출력.
check_secret_template(template_id) - 시크릿 템플릿 세부 정보 가져오기.
check_secret_template_field(template_id, field_id) - 템플릿에 필드가 포함되어 있는지 확인.
get_secret_template_field(field_id) - ID로 특정 시크릿 템플릿 필드에 대한 세부 정보 검색.
handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - 액세스 요청 승인 또는 거부.
get_pending_access_requests() - 보류 중인 액세스 요청 나열.
get_inbox_messages(read_status_filter=None, take=20, skip=0) - 받은 편지함 메시지 검색.
mark_inbox_messages_read(message_ids, read=True) - 메시지를 읽음 또는 읽지 않음으로 표시.
user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - 통합 사용자 작업. action은 get, create, update, delete, list_sessions, reset_2fa, reset_password 또는 lock_out를 허용합니다. 필요할 때 user_id을 제공하고 생성, 업데이트 및 비밀번호 재설정 작업을 위해 data을 통해 요청 본문을 제공하십시오. 예: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
role_management(action, role_id=None, data=None, params=None) - 역할 관리. action는 list, get, create 또는 update일 수 있습니다. 역할을 나열할 때 params로 선택적 쿼리 매개변수를 전달하십시오. 예: role_management("update", role_id=3, data={"name": "New Role"}).
user_role_management(action, user_id, role_ids=None) - 사용자에게 역할 할당 또는 제거. action는 get, add 또는 remove이고 role_ids은 추가/제거 작업을 위한 역할 식별자 목록입니다.
group_management(action, group_id=None, data=None, params=None) - 그룹 처리. action은 get, list, create 또는 delete일 수 있습니다. 가져오기/삭제 시 group_id을 제공하고 그룹 생성 시 data를 제공하십시오.
folder_management(action, folder_id=None, data=None, params=None) - 폴더 관리. action은 get, list, create, update 또는 delete일 수 있습니다. 가져오기, 업데이트 또는 삭제 시 folder_id를 제공하고 폴더 생성 또는 업데이트 시 data을 제공하십시오.
user_group_management(action, user_id, group_ids=None) - 사용자의 그룹 멤버십 관리. action는 get, add 또는 remove입니다. 멤버십 추가 또는 제거 시 group_ids 목록을 제공하십시오.
group_role_management(action, group_id, role_ids=None) - 그룹의 역할 제어. list, add 또는 remove 작업을 사용하십시오. 추가 또는 제거 시 role_ids를 제공하십시오.
health_check() - Secret Server 상태 확인 엔드포인트를 쿼리하고 현재 서비스 상태를 반환합니다.

인증하려면 위에서 설명한 서버 구성 변수를 사용하십시오. Azure OpenAI 변수가 누락된 경우 AI 도구는 자동으로 비활성화됩니다. config.json에 나열된 도구 이름만 등록됩니다. 빈 목록은 모든 도구를 활성화합니다.

사용 사례

문서는 도구를 서버에 연결하기 위한 여러 워크플로를 다룹니다:

Docker 빠른 시작

로컬에 Python 종속성을 설치하지 않고 MCP 서버를 실행하기 위한 Dockerfile이 제공됩니다.

이미지 빌드:

docker build -t dev.local/delinea-mcp:latest .

서버 실행 (환경 변수를 통해 자격 증명 전달):

docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

위에 표시된 대로 사용자 이름과 URL로 config.json을 채우십시오.

컨테이너는 oauth.db 및 jwt.json을 /app/data에 저장합니다. 이러한 파일과 HTTPS 인증서가 실행 간에 유지되도록 볼륨을 마운트하십시오 (위에서 mcp-data로 표시됨).

연결 오류를 방지하려면 <https://your-secret-server/SecretServer>을 Secret Server 인스턴스의 기본 URL로 바꾸십시오.

서버는 기본적으로 python server.py을 사용하여 포트 8000에서 시작됩니다. 기본값을 재정의하려면 config.json에서 port 옵션을 설정하십시오. 들어오는 모든 HTTP 요청을 기록하려면 debug: true을 활성화하십시오.

예제 스크립트

manual_secret_request.py 스크립트는 특정 시크릿 ID에 대한 OAuth 토큰을 검색하는 방법을 보여줍니다:

python scripts/manual_secret_request.py <Secret_ID>

스크립트를 실행하기 전에 시크릿에 대한 환경 변수 SECRET_USERNAME_<id> 및 SECRET_PASSWORD_<id>을 설정하십시오. 선택적으로 DELINEA_BASE_URL를 설정하여 기본 https://localhost/SecretServer을 재정의할 수 있습니다.

테스트 실행

100% 코드 커버리지를 보장하기 위해 커버리지와 함께 단위 테스트 실행:

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

라이브 테스트

일부 통합 테스트에는 유효한 자격 증명이 필요합니다. 스위트를 실행하기 전에 다음 환경 변수와 선택적 LIVE_SECRET_ID를 설정하십시오:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

이러한 변수가 있으면 라이브 테스트가 실제 API 요청을 수행합니다.

프로덕션 배포

종속성은 requirements.txt에 고정되어 있으며 릴리스는 Semantic Versioning을 사용하여 태그가 지정됩니다. 태그가 지정된 커밋에서 Docker 이미지를 빌드하고 필요한 환경 변수 (DELINEA_USERNAME, DELINEA_PASSWORD, 선택적으로 DELINEA_BASE_URL)를 전달하여 프로덕션 환경에 배포하십시오. 선택적 기능은 추가 변수에 의존합니다:

PLATFORM_SERVICE_PASSWORD와 PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT 및 PLATFORM_TENANT_ID는 사용자 관리 도구를 활성화합니다.
AZURE_OPENAI_KEY과 AZURE_OPENAI_ENDPOINT 및 AZURE_OPENAI_DEPLOYMENT는 AI 보고서 생성 도우미를 활성화합니다.

OAuth 또는 SSE 전송으로 실행할 때 registration_psk을 제공하고 external_hostname 또는 HTTPS 인증서 파일을 구성해야 할 수 있습니다.

저장소 레이아웃

delinea_mcp/ - MCP 도구를 포함하는 패키지.
server.py - MCP 서버에 모든 것을 등록하는 씬 진입점.
docs/ - 프로젝트 문서 및 생성된 delinea-secret-server-openapi-spec.json.
scripts/ - manual_secret_request.py을 포함한 도우미 예제.

보안 고려 사항

포함된 OAuth 엔드포인트는 개발 및 테스트용입니다. /oauth/authorize 경로는 모든 redirect_uri을 허용하며 유효성 검사 없이 사용자를 리디렉션합니다. 배포 시 반드시 이 값을 승인된 콜백 URL로 제한해야 합니다. 그렇지 않으면 공격자가 악의적인 URL을 제공하여 인증 코드를 캡처할 수 있습니다. 배경 정보는 Open Redirection을 참조하십시오.

릴리스 노트

최신 기능 및 로드맵 항목 요약은 docs/release_notes.md를 참조하십시오.

로드맵

통과 인증
스트리밍 HTTP 전송 지원
Delinea Platform에서 도구 범위 확장 및 다른 Delinea 제품 추가

기여

기여를 환영합니다! 개선 사항이 있으면 이슈 또는 풀 리퀘스트를 열어주십시오. 모든 새 코드는 단위 테스트를 포함하고 기존 테스트 스위트를 통과해야 합니다.

라이선스

이 프로젝트는 MIT License에 따라 라이선스가 부여됩니다.