Vertex AI MCP 서버
이 프로젝트는 Google Cloud의 Vertex AI Gemini 모델과 상호 작용하기 위한 포괄적인 도구 모음을 제공하는 MCP(Model Context Protocol) 서버를 구현하며, 코딩 지원과 일반적인 쿼리 답변에 중점을 둡니다.
특징
다양한 MCP 도구를 통해 Vertex AI Gemini 모델에 대한 액세스를 제공합니다.
웹 검색 기반(
answer_query_websearch)과 직접 지식 답변(answer_query_direct)을 지원합니다.환경 변수를 통해 구성 가능한 모델 ID, 온도, 스트리밍 동작, 최대 출력 토큰 및 재시도 설정.
기본적으로 스트리밍 API를 사용하여 응답성을 높일 수 있습니다.
일시적인 API 오류에 대한 기본 재시도 논리가 포함되어 있습니다.
잠재적인 차단을 줄이기 위해 최소한의 안전 필터(
BLOCK_NONE)가 적용되었습니다(신중하게 사용하세요).
Related MCP server: mcp-google
제공된 도구
쿼리 및 생성(AI 중심)
answer_query_websearch: Google 검색 결과로 강화된 구성된 Vertex AI 모델을 사용하여 자연어 쿼리에 답변합니다.answer_query_direct: 구성된 Vertex AI 모델의 내부 지식만을 사용하여 자연어 쿼리에 답변합니다.explain_topic_with_docs: 웹 검색을 통해 찾은 공식 문서의 정보를 종합하여 특정 소프트웨어 주제에 대한 질의에 대한 자세한 설명을 제공합니다.get_doc_snippets: 공식 문서를 검색하여 정확하고 권위 있는 코드 조각이나 기술적 질문에 대한 간결한 답변을 제공합니다.generate_project_guidelines: 웹 검색을 통해 모범 사례를 찾아 지정된 기술 목록(선택적으로 버전 포함)을 기반으로 구조화된 프로젝트 가이드라인 문서(마크다운)를 생성합니다.
파일 시스템 작업
read_file_content: 단일 파일의 전체 내용을 읽습니다.read_multiple_files_content: 여러 파일의 내용을 동시에 읽습니다.write_file_content: 새 파일을 만들거나 기존 파일을 새 내용으로 완전히 덮어씁니다.edit_file_content: 텍스트 파일에 줄 기반 편집을 수행하여 차이점 미리 보기를 반환하거나 변경 사항을 적용합니다.create_directory: 새로운 디렉토리(중첩된 디렉토리 포함)를 생성합니다.list_directory_contents: 지정된 경로 내에 있는 파일과 디렉토리를 직접 나열합니다(비재귀적).get_directory_tree: 파일과 디렉토리의 재귀적 트리 뷰를 JSON으로 가져옵니다.move_file_or_directory: 파일과 디렉토리를 이동하거나 이름을 바꿉니다.search_filesystem: 선택적으로 제외 항목을 포함하여 이름 패턴과 일치하는 파일/디렉토리를 재귀적으로 검색합니다.get_filesystem_info: 파일이나 디렉토리에 대한 자세한 메타데이터(크기, 날짜, 유형, 권한)를 검색합니다.
AI + 파일 시스템 작업 결합
save_generate_project_guidelines: 기술 스택을 기반으로 프로젝트 가이드라인을 생성하고 결과를 지정된 파일 경로에 저장합니다.save_doc_snippet: 문서에서 코드 조각을 찾아 지정된 파일 경로에 결과를 저장합니다.save_topic_explanation: 문서를 기반으로 주제에 대한 자세한 설명을 생성하고 결과를 지정된 파일 경로에 저장합니다.save_answer_query_direct: 내부 지식만을 사용하여 쿼리에 답변하고 지정된 파일 경로에 답변을 저장합니다.save_answer_query_websearch: 웹 검색 결과를 사용하여 쿼리에 답변하고 지정된 파일 경로에 답변을 저장합니다.
(참고: 각 도구의 입출력 스키마는
필수 조건
Node.js(v18+)
Bun (
npm install -g bun)결제가 활성화된 Google Cloud 프로젝트입니다.
GCP 프로젝트에서 Vertex AI API가 활성화되었습니다.
사용자 환경에 구성된 Google Cloud 인증(
gcloud auth application-default login통한 애플리케이션 기본 자격 증명 또는 서비스 계정 키가 권장됨).
설정 및 설치
프로젝트 복제/배치: 프로젝트 파일이 원하는 위치에 있는지 확인하세요.
종속성 설치:
지엑스피1
환경 구성:
프로젝트 루트에
.env파일을 만듭니다(복사.env.example)..env.example에 설명된 대로 필수 및 선택 환경 변수를 설정합니다.AI_PROVIDER``"vertex"또는"gemini"로 설정합니다.AI_PROVIDER="vertex"인 경우GOOGLE_CLOUD_PROJECT가 필요합니다.AI_PROVIDER="gemini"이면GEMINI_API_KEY가 필요합니다.
서버 구축:
bun run build이렇게 하면 TypeScript 코드가
build/index.js로 컴파일됩니다.
사용법(독립형/NPX)
npm에 게시한 후 npx 사용하여 이 서버를 직접 실행할 수 있습니다.
또는 전역적으로 설치하세요.
참고: 독립 실행형으로 실행하려면 명령을 실행하기 전에 셸 환경에서 필요한 환경 변수(예: GOOGLE_CLOUD_PROJECT , GOOGLE_CLOUD_LOCATION , ADC를 사용하지 않는 경우 인증 자격 증명)를 설정해야 합니다.
Smithery를 통해 설치
Smithery 를 통해 Claude Desktop에 Vertex AI Server를 자동으로 설치하는 방법:
클라인과 함께 달리기
MCP 설정 구성: Cline MCP 설정 파일(예:
.roo/mcp.json)에 구성을 추가/업데이트합니다. 명령을 구성하는 주요 방법은 두 가지입니다.옵션 A: 노드 사용(직접 경로 - 개발에 권장)
이 방법은
node사용하여 컴파일된 스크립트를 직접 실행합니다. 개발 중에 코드를 로컬에 복제할 때 유용합니다.{ "mcpServers": { "vertex-ai-mcp-server": { "command": "node", "args": [ "/full/path/to/your/vertex-ai-mcp-server/build/index.js" // Use absolute path or ensure it's relative to where Cline runs node ], "env": { // --- General AI Configuration --- "AI_PROVIDER": "vertex", // "vertex" or "gemini" // --- Required (Conditional) --- "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex" // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini" // --- Optional Model Selection --- "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override) "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini" // --- Optional AI Parameters --- "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI "AI_TEMPERATURE": "0.0", "AI_USE_STREAMING": "true", "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example "AI_MAX_RETRIES": "3", "AI_RETRY_DELAY_MS": "1000", // --- Optional Vertex Authentication --- // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex }, "disabled": false, "alwaysAllow": [ // Add tool names here if you don't want confirmation prompts // e.g., "answer_query_websearch" ], "timeout": 3600 // Optional: Timeout in seconds } // Add other servers here... } }중요:
args경로가build/index.js파일을 올바르게 가리키는지 확인하세요. 절대 경로를 사용하는 것이 더 안전할 수 있습니다.
옵션 B: NPX 사용(npm에 게시된 패키지 필요)
이 방법은
npx사용하여 npm 레지스트리에서 서버 패키지를 자동으로 다운로드하고 실행합니다. 저장소를 복제하지 않으려는 경우 편리합니다.{ "mcpServers": { "vertex-ai-mcp-server": { "command": "bunx", // Use bunx "args": [ "-y", // Auto-confirm installation "vertex-ai-mcp-server" // The npm package name ], "env": { // --- General AI Configuration --- "AI_PROVIDER": "vertex", // "vertex" or "gemini" // --- Required (Conditional) --- "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex" // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini" // --- Optional Model Selection --- "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override) "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini" // --- Optional AI Parameters --- "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI "AI_TEMPERATURE": "0.0", "AI_USE_STREAMING": "true", "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example "AI_MAX_RETRIES": "3", "AI_RETRY_DELAY_MS": "1000", // --- Optional Vertex Authentication --- // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex }, "disabled": false, "alwaysAllow": [ // Add tool names here if you don't want confirmation prompts // e.g., "answer_query_websearch" ], "timeout": 3600 // Optional: Timeout in seconds } // Add other servers here... } }env블록의 환경 변수가.env와 일치하거나 여기에 명시적으로 정의되어 올바르게 설정되었는지 확인하세요. 실제 JSON 파일에서 주석을 제거하세요.
Cline 재시작/다시 로드: Cline은 구성 변경을 감지하고 서버를 시작해야 합니다.
도구 사용: 이제 Cline을 통해 광범위한 도구 목록을 사용할 수 있습니다.
개발
시계 모드:
bun run watch린팅:
bun run lint포맷:
bun run format
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.