Gemini File Search MCP Server

This is a Model Context Protocol (MCP) server that allows AI agents to query your local project files using Google's Gemini File Search API.

It automatically detects your project configuration from the document-sync.json file created by the Gemini File Sync VS Code extension.

Demo

Related Extensions

This MCP server works seamlessly with the Document Sync extension for VS Code and Cursor, which automatically syncs your project files to Google's Gemini File Search API.

VS Code Extension

Install the Document Sync extension from the VS Code Marketplace to:

• Automatically sync files to Gemini File Search when you save changes
• Organize files by project name for better management
• Selectively watch and sync specific directories
• Securely store your Gemini API key

Cursor Extension

The same extension is also available for Cursor. Install it from:

• VS Code Marketplace (works in Cursor)
• Open VSX (open-source alternative)

How They Work Together

1. Install the Extension: Install Document Sync in VS Code or Cursor
2. Sync Your Files: Use the extension to sync your project files to Gemini File Search
3. Use the MCP Server: This MCP server allows AI agents (like Claude Desktop or Cursor's AI) to query your synced files
4. Automatic Updates: As you work, the extension keeps your files in sync, and the MCP server provides real-time access to your codebase

The extension creates a document-sync.json file in your project root, which this MCP server uses to automatically detect your project configuration.

Prerequisites

1. Node.js: Ensure Node.js is installed.
2. Gemini API Key: You need a valid API Key from Google AI Studio.
3. Project Configuration: You must have run the Gemini File Sync extension in your project at least once to generate the document-sync.json file in your project root.

Installation

You can install this server directly from npm:

npm install -g @shoutoutlabs/document-sync-mcp

Or run it directly with npx:

npx @shoutoutlabs/document-sync-mcp

Running the Server

Environment Variables

• GEMINI_API_KEY: Required. Your Google Gemini API Key.
• PROJECT_PATH: Optional. Absolute path to your project root. Use this if the server cannot find document-sync.json automatically (e.g., when running from a different directory).

Manual Run

export GEMINI_API_KEY="your_api_key_here"
npx @shoutoutlabs/document-sync-mcp

HTTP/SSE Transport Mode

The server also supports HTTP/SSE transport for web-based clients and remote connections. To run the server in HTTP mode:

export GEMINI_API_KEY="your_api_key_here"
export PORT=3000  # Optional, defaults to 3000
npm run serve:http
# or after building:
node build/httpServer.js

The HTTP server provides the following endpoints:

• POST /mcp: Standard HTTP JSON-RPC endpoint for MCP protocol messages
• GET /sse: Server-Sent Events (SSE) endpoint for streaming connections
• POST /sse: POST endpoint for sending requests when using SSE transport
• GET /health: Health check endpoint

Example: Using HTTP Transport

# Start the HTTP server
export GEMINI_API_KEY="your_api_key_here"
npm run serve:http

# The server will be available at:
# - HTTP POST: http://localhost:3000/mcp
# - SSE: http://localhost:3000/sse
# - Health: http://localhost:3000/health

Example: Sending a request via HTTP POST

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_projects",
      "arguments": {}
    }
  }'

Example: Using SSE Transport

1. Connect to the SSE endpoint:

curl -N http://localhost:3000/sse

2. Send requests via POST to /sse:

curl -X POST http://localhost:3000/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_projects",
      "arguments": {}
    }
  }'

Responses will be streamed back through the SSE connection.

Adding to Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gemini-file-search": {
      "command": "npx",
      "args": [
        "-y",
        "@shoutoutlabs/document-sync-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Adding to Cursor

1. Open Cursor Settings.
2. Navigate to Features > MCP.
3. Click Add New MCP Server.
4. Name: gemini-file-search (or any name you prefer).
5. Type: command.
6. Command:

   npx -y @shoutoutlabs/document-sync-mcp

7. Environment Variables:
   • Key: GEMINI_API_KEY
   • Value: your_api_key_here

Available Tools

• ask_project(query: string, projectName?: string): Ask a question about the current project.
  • query: The question to ask.
  • projectName: (Optional) The name of the project. If provided, the server uses this name to find files. If not provided, it attempts to find document-sync.json in the current or parent directories.
• list_projects(): List all available Gemini File Search projects (File Search stores) accessible with the current GEMINI_API_KEY.

Web Client

The application also includes a web-client that can run on your own server. This provides a powerful web interface to manage and interact with your synced documents and projects.

Features

• View Synced Documents: All documents and projects synced via the extension can be viewed in the web interface
• Project Management: Manage your projects, knowledge bases, and documents through an intuitive web dashboard
• Team Collaboration: Provide access to your dashboard for other teams (marketing, sales, etc.) so they have up-to-date documentation to retrieve information
• MCP Server Integration: With the MCP server, you can get relevant application context directly in the chat interface
• Multi-Repository Support: Ideal for managing multiple repositories for the same project (such as microservices), providing the same knowledge base across all repos

Advantages

• Team Access: Share your documentation dashboard with non-technical team members who need access to up-to-date project information
• Context-Aware Chat: The web client integrates with the MCP server to provide relevant application context during chat interactions
• Unified Knowledge Base: Perfect for microservices architectures where you want a single knowledge base accessible across multiple repositories

Running the Web Client

See the web-client README for detailed setup instructions. The web client can be configured to use your Gemini API key via environment variable or entered directly in the interface.

Important: To see the same projects across the extension, MCP server, and web client, you must use the same Gemini API key in all three components. Each API key has its own set of File Search stores, so using different keys will show different projects.