Skip to content
Back to search

vertex-ai-mcp-server

MCP server for Vertex AI and Gemini tools, including grounded answers, documentation research, and filesystem workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/shariqriazz--vertex-ai-mcp-server/badge.svg)](/listings/shariqriazz--vertex-ai-mcp-server)

HTML

<a href="/listings/shariqriazz--vertex-ai-mcp-server"><img src="/api/listings/shariqriazz--vertex-ai-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Clone/Place Project:** Ensure the project files are in your desired location. 2. **Install Dependencies:** ```bash bun install ``` 3. **Configure Environment:** * Create a `.env` file in the project root (copy `.env.example`). * Set the required and optional environment variables as described in `.env.example`. * Set `AI_PROVIDER` to either `"vertex"` or `"gemini"`. * If `AI_PROVIDER="vertex"`, `GOOGLE_CLOUD_PROJECT` is required. * If `AI_PROVIDER="gemini"`, `GEMINI_API_KEY` is required. 4. **Build the Server:** ```bash bun run build ``` This compiles the TypeScript code to `build/index.js`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 226 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/shariqriazz-vertex-ai-mcp-server-badge.png)](https://mseep.ai/app/shariqriazz-vertex-ai-mcp-server)
  2. # Vertex AI MCP Server
  3. [![smithery badge](https://smithery.ai/badge/@shariqriazz/vertex-ai-mcp-server)](https://smithery.ai/server/@shariqriazz/vertex-ai-mcp-server)
  4. This project implements a Model Context Protocol (MCP) server that provides a comprehensive suite of tools for interacting with Google Cloud's Vertex AI Gemini models, focusing on coding assistance and general query answering.
  5. <a href="https://glama.ai/mcp/servers/@shariqriazz/vertex-ai-mcp-server">
  6. <img width="380" height="200" src="https://glama.ai/mcp/servers/@shariqriazz/vertex-ai-mcp-server/badge" alt="Vertex AI Server MCP server" />
  7. </a>
  8. ## Security boundary
  9. This server includes filesystem write and terminal-execution tools in addition to model and research tools. Run it with a dedicated low-privilege identity, limit its filesystem and network access, and keep consequential tools behind explicit approval. Do not treat an MCP client confirmation prompt as server-side authorization.
  10. For the implementation tradeoffs this project exposed alongside six other public MCP codebases, see [What building seven MCP servers taught me about production MCP](https://www.orchestriai.com/blog/lessons-building-seven-mcp-servers). The article uses this repository as public engineering evidence; it does not claim that every production control discussed there is already implemented here.
  11. ## Features
  12. * Provides access to Vertex AI Gemini models via numerous MCP tools.
  13. * Supports web search grounding (`answer_query_websearch`) and direct knowledge answering (`answer_query_direct`).
  14. * Configurable model ID, temperature, streaming behavior, max output tokens, and retry settings via environment variables.
  15. * Uses streaming API by default for potentially better responsiveness.
  16. * Includes basic retry logic for transient API errors.
  17. * Minimal safety filters applied (`BLOCK_NONE`) to reduce potential blocking (use with caution).
  18. ## Tools Provided
  19. ### Query & Generation (AI Focused)
  20. * `answer_query_websearch`: Answers a natural language query using the configured Vertex AI model enhanced with Google Search results.
  21. * `answer_query_direct`: Answers a natural language query using only the internal knowledge of the configured Vertex AI model.
  22. * `explain_topic_with_docs`: Provides a detailed explanation for a query about a specific software topic by synthesizing information primarily from official documentation found via web search.
  23. * `get_doc_snippets`: Provides precise, authoritative code snippets or concise answers for technical queries by searching official documentation.
  24. * `generate_project_guidelines`: Generates a structured project guidelines document (Markdown) based on a specified list of technologies (optionally with versions), using web search for best practices.
  25. ### Research & Analysis Tools
  26. * `code_analysis_with_docs`: Analyzes code snippets by comparing them with best practices from official documentation, identifying potential bugs, performance issues, and security vulnerabilities.
  27. * `technical_comparison`: Compares multiple technologies, frameworks, or libraries based on specific criteria, providing detailed comparison tables with pros/cons and use cases.
  28. * `architecture_pattern_recommendation`: Suggests architecture patterns for specific use cases based on industry best practices, with implementation examples and considerations.
  29. * `dependency_vulnerability_scan`: Analyzes project dependencies for known security vulnerabilities, providing detailed information and mitigation strategies.
  30. * `database_schema_analyzer`: Reviews database schemas for normalization, indexing, and performance issues, suggesting improvements based on database-specific best practices.
  31. * `security_best_practices_advisor`: Provides security recommendations for specific technologies or scenarios, with code examples for implementing secure practices.
  32. * `testing_strategy_generator`: Creates comprehensive testing strategies for applications or features, suggesting appropriate testing types with coverage goals.
  33. * `regulatory_compliance_advisor`: Provides guidance on regulatory requirements for specific industries (GDPR, HIPAA, etc.), with implementation approaches for compliance.
  34. * `microservice_design_assistant`: Helps design microservice architectures for specific domains, with service boundary recommendations and communication patterns.
  35. * `documentation_generator`: Creates comprehensive documentation for code, APIs, or systems, following industry best practices for technical documentation.
  36. ### Filesystem Operations
  37. * `read_file_content`: Read the complete contents of one or more files. Provide a single path string or an array of path strings.
  38. * `write_file_content`: Create new files or completely overwrite existing files. The 'writes' argument accepts a single object (`{path, content}`) or an array of such objects.
  39. * `edit_file_content`: Makes line-based edits to a text file, returning a diff preview or applying changes.
  40. * `list_directory_contents`: Lists files and directories directly within a specified path (non-recursive).
  41. * `get_directory_tree`: Gets a recursive tree view of files and directories as JSON.
  42. * `move_file_or_directory`: Moves or renames files and directories.
  43. * `search_filesystem`: Recursively searches for files/directories matching a name pattern, with optional exclusions.
  44. * `get_filesystem_info`: Retrieves detailed metadata (size, dates, type, permissions) about a file or directory.
  45. * `execute_terminal_command`: Execute a shell command, optionally specifying `cwd` and `timeout`. Returns stdout/stderr.
  46. ### Combined AI + Filesystem Operations
  47. * `save_generate_project_guidelines`: Generates project guidelines based on a tech stack and saves the result to a specified file path.
  48. * `save_doc_snippet`: Finds code snippets from documentation and saves the result to a specified file path.
  49. * `save_topic_explanation`: Generates a detailed explanation of a topic based on documentation and saves the result to a specified file path.
  50. * `save_answer_query_direct`: Answers a query using only internal knowledge and saves the answer to a specified file path.
  51. * `save_answer_query_websearch`: Answers a query using web search results and saves the answer to a specified file path.
  52. *(Note: Input/output schemas for each tool are defined in their respective files within `src/tools/` and exposed via the MCP server.)*
  53. ## Prerequisites
  54. * Node.js (v18+)
  55. * Bun (`npm install -g bun`)
  56. * Google Cloud Project with Billing enabled.
  57. * Vertex AI API enabled in the GCP project.
  58. * Google Cloud Authentication configured in your environment (Application Default Credentials via `gcloud auth application-default login` is recommended, or a Service Account Key).
  59. ## Setup & Installation
  60. 1. **Clone/Place Project:** Ensure the project files are in your desired location.
  61. 2. **Install Dependencies:**
  62. ```bash
  63. bun install
  64. ```
  65. 3. **Configure Environment:**
  66. * Create a `.env` file in the project root (copy `.env.example`).
  67. * Set the required and optional environment variables as described in `.env.example`.
  68. * Set `AI_PROVIDER` to either `"vertex"` or `"gemini"`.
  69. * If `AI_PROVIDER="vertex"`, `GOOGLE_CLOUD_PROJECT` is required.
  70. * If `AI_PROVIDER="gemini"`, `GEMINI_API_KEY` is required.
  71. 4. **Build the Server:**
  72. ```bash
  73. bun run build
  74. ```
  75. This compiles the TypeScript code to `build/index.js`.
  76. ## Usage (Standalone / NPX)
  77. Once published to npm, you can run this server directly using `npx`:
  78. ```bash
  79. # Ensure required environment variables are set (e.g., GOOGLE_CLOUD_PROJECT)
  80. bunx vertex-ai-mcp-server
  81. ```
  82. Alternatively, install it globally:
  83. ```bash
  84. bun install -g vertex-ai-mcp-server
  85. # Then run:
  86. vertex-ai-mcp-server
  87. ```
  88. **Note:** Running standalone requires setting necessary environment variables (like `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, authentication credentials if not using ADC) in your shell environment before executing the command.
  89. ### Installing via Smithery
  90. To install Vertex AI Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@shariqriazz/vertex-ai-mcp-server):
  91. ```bash
  92. bunx -y @smithery/cli install @shariqriazz/vertex-ai-mcp-server --client claude
  93. ```
  94. ## Running with Cline
  95. 1. **Configure MCP Settings:** Add/update the configuration in your Cline MCP settings file (e.g., `.roo/mcp.json`). You have two primary ways to configure the command:
  96. **Option A: Using Node (Direct Path - Recommended for Development)**
  97. This method uses `node` to run the compiled script directly. It's useful during development when you have the code cloned locally.
  98. ```json
  99. {
  100. "mcpServers": {
  101. "vertex-ai-mcp-server": {
  102. "command": "node",
  103. "args": [
  104. "/full/path/to/your/vertex-ai-mcp-server/build/index.js" // Use absolute path or ensure it's relative to where Cline runs node
  105. ],
  106. "env": {
  107. // --- General AI Configuration ---
  108. "AI_PROVIDER": "vertex", // "vertex" or "gemini"
  109. // --- Required (Conditional) ---
  110. "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
  111. // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
  112. // --- Optional Model Selection ---
  113. "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override)
  114. "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini"
  115. // --- Optional AI Parameters ---
  116. "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
  117. "AI_TEMPERATURE": "0.0",
  118. "AI_USE_STREAMING": "true",
  119. "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
  120. "AI_MAX_RETRIES": "3",
  121. "AI_RETRY_DELAY_MS": "1000",
  122. // --- Optional Vertex Authentication ---
  123. // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
  124. },
  125. "disabled": false,
  126. "alwaysAllow": [
  127. // Add tool names here if you don't want confirmation prompts
  128. // e.g., "answer_query_websearch"
  129. ],
  130. "timeout": 3600 // Optional: Timeout in seconds
  131. }
  132. // Add other servers here...
  133. }
  134. }
  135. ```
  136. * **Important:** Ensure the `args` path points correctly to the `build/index.js` file. Using an absolute path might be more reliable.
  137. **Option B: Using NPX (Requires Package Published to npm)**
  138. This method uses `npx` to automatically download and run the server package from the npm registry. This is convenient if you don't want to clone the repository.
  139. ```json
  140. {
  141. "mcpServers": {
  142. "vertex-ai-mcp-server": {
  143. "command": "bunx", // Use bunx
  144. "args": [
  145. "-y", // Auto-confirm installation
  146. "vertex-ai-mcp-server" // The npm package name
  147. ],
  148. "env": {
  149. // --- General AI Configuration ---
  150. "AI_PROVIDER": "vertex", // "vertex" or "gemini"
  151. // --- Required (Conditional) ---
  152. "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
  153. // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
  154. // --- Optional Model Selection ---
  155. "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override)
  156. "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini"
  157. // --- Optional AI Parameters ---
  158. "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
  159. "AI_TEMPERATURE": "0.0",
  160. "AI_USE_STREAMING": "true",
  161. "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
  162. "AI_MAX_RETRIES": "3",
  163. "AI_RETRY_DELAY_MS": "1000",
  164. // --- Optional Vertex Authentication ---
  165. // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
  166. },
  167. "disabled": false,
  168. "alwaysAllow": [
  169. // Add tool names here if you don't want confirmation prompts
  170. // e.g., "answer_query_websearch"
  171. ],
  172. "timeout": 3600 // Optional: Timeout in seconds
  173. }
  174. // Add other servers here...
  175. }
  176. }
  177. ```
  178. * Ensure the environment variables in the `env` block are correctly set, either matching `.env` or explicitly defined here. Remove comments from the actual JSON file.
  179. 2. **Restart/Reload Cline:** Cline should detect the configuration change and start the server.
  180. 3. **Use Tools:** You can now use the extensive list of tools via Cline.
  181. ## Development
  182. * **Watch Mode:** `bun run watch`
  183. * **Linting:** `bun run lint`
  184. * **Formatting:** `bun run format`
  185. ## License
  186. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.