GroundX

This MCP server enables GroundX access through a local proxy, exposing a practical path to parse and semantically search your documents via the GroundX API. It supports a Google Drive integration and is designed to work with Claude Desktop and GitHub Copilot to streamline document handling and retrieval tasks across local files and Drive.

How to use

Use the GroundX MCP Server through either the local stdio servers you run in a WSL environment or by connecting to a remote MCP URL. Start the local servers, ensure your GroundX API key is set, and configure Claude Desktop or VS Code Copilot to discover and use the MCP tools. You can upload local files to GroundX, sync Google Drive documents, perform semantic searches across your documents, and retrieve knowledge from GroundX through natural language queries.

Typical workflows include: uploading a local document to a GroundX bucket, locating specific Drive documents for ingestion, performing a semantic search over GroundX documents, and answering questions based on the integrated document set. The agent will automatically invoke the correct MCP tool for each task once it is configured in Claude Desktop or VS Code Copilot.

How to install

Prerequisites and environment setup you need to prepare before running the MCP servers.

// Minimal prerequisites and steps to install the GroundX MCP Server locally
// 1. Clone the repository
git clone https://github.com/Geoffrey-42/rag-groundx-mcp-server.git
cd rag-groundx-mcp-server

// 2. Set up the virtual environment using uv
uv venv

// 3. Activate the virtual environment
source .venv/bin/activate

// 4. Install dependencies
uv pip install -r requirements.txt

// 5. Create and configure environment variables
// Required: GroundX API key, optional: Google Drive server URL
touch .env

The following environment variables should be set in a .env file or environment at runtime.

# .env (example)
GROUNDX_API_KEY=your_groundx_api_key_here
# Optional: for Google Drive integration
GOOGLE_DRIVE_SERVER_URL=your_google_drive_mcp_server_url

Claude Desktop configuration and startup

Configure Claude Desktop to run both the GroundX MCP Server and the Google Drive Proxy Server through a Windows Subsystem for Linux (WSL) session. This enables Claude and VS Code to discover and use the MCP tools automatically.

{
  "mcpServers": {
    "Groundx_RAG_MCP_Server": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "-e", "bash", "-c",
        "export GROUNDX_API_KEY=<your_groundx_api_key> && export PATH=$HOME/.local/bin:$PATH && cd /home/<your-name>/<project-folder>/rag-groundx-mcp-server/src && uv run Groundx_RAG_MCP_Server.py"
      ],
      "env": {
        "GROUNDX_API_KEY": "<your_groundx_api_key>"
      }
    },
    "GoogleDriveProxyServer": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "-e", "bash", "-c",
        "export GOOGLE_DRIVE_SERVER_URL=<your_google_drive_mcp_server_url> && export PATH=$HOME/.local/bin:$PATH && cd /home/<your-name>/<project-folder>/rag-groundx-mcp-server/src && uv run Google_Drive_Proxy_Server.py"
      ],
      "env": {
        "GOOGLE_DRIVE_SERVER_URL": "<your_google_drive_mcp_server_url>"
      }
    }
  }
}

Starting and using the servers

With the servers configured, start Claude Desktop and VS Code. Ensure Agent mode is enabled in VS Code Copilot and enable the MCP tools in Claude Desktop. The tools will be detected automatically and you can begin issuing natural language requests to interact with GroundX documents.

If you prefer using environment variables, place the credentials in a .env file and ensure the paths in the start commands point to your project folder for GroundX and the Google Drive proxy.

Notes and troubleshooting

You can run both the GroundX MCP Server and the Google Drive Proxy Server via the same Claude Desktop configuration. If you encounter issues, restart Claude Desktop and VS Code to re-detect tools, and verify that the environment variables are correctly set.

Example interaction patterns

General information: List your GroundX buckets and Google Drive documents. Upload local files: Upload a file from your machine to a GroundX bucket. Find documents: Locate a file in Google Drive and prepare it for ingestion. Upload documents: Add a Google Drive document to GroundX. Retrieve knowledge: Ask a question that leverages content from GroundX documents.

Available tools

Retrieval_from_Groundx

Performs semantic search across your GroundX documents to retrieve relevant results.

upload_local_file_to_Groundx

Uploads a local file to a GroundX bucket for ingestion and indexing.

upload_remote_file_to_Groundx

Uploads a file from a public URL to GroundX for ingestion.

crawl_website_to_Groundx

Crawls a website and uploads its content to GroundX.

google_drive_retrieve_files_from_google_drive

Retrieves details of a specific document from Google Drive via the configured Google Drive MCP Server URL.