Nathanf22/gcs_mcp_server

GCS MCP Server

This project provides a Multi-Capability Protocol (MCP) server for interacting with Google Cloud Storage (GCS). It is designed to be used by AI agents, providing a tool-based interface for managing GCS resources like buckets and objects.

The server is built using Python with the FastMCP framework.

Features

• Bucket Management: Create and delete GCS buckets.
• Object Operations: Upload, read, delete, and move files (including binary files).
• Directory Listing: List the contents of buckets or specific directories.
• Self-Documentation: An agent can retrieve the server's full API documentation by calling the get_mcp_documentation tool.

Getting Started

Prerequisites

• Python 3.10+
• uv package manager (pip install uv)
• Google Cloud SDK (gcloud) installed and authenticated.

Setup and Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd gcs_mcp_server
   

2. Set up the Python environment: This project uses the .python-version file to specify the Python version. If you have a tool like pyenv or rtx, it will be used automatically.

3. Create the virtual environment and install dependencies:

   uv venv
   uv sync
   

4. Set up Google Cloud Authentication:

   • Authenticate the gcloud CLI:

     gcloud auth login
     gcloud auth application-default login
     

   • Create a service_account_key.json file in the root of the project with your Google Cloud service account credentials. This file is already listed in .gitignore and will not be committed to your repository.

Running the Server Locally

To start the server, run the following command:

uv run gcs-mcp-server

The server will be available at http://localhost:8080.

Running Tests

The integration test suite validates all server functionality against a live GCS environment.

1. Start the server in one terminal: uv run gcs-mcp-server
2. Run the tests in a second terminal:

   uv run pytest --run-integration -m integration --verbose tests/integration_test.py
   

Deployment

This project includes a Dockerfile and a deploy.bat script for easy deployment to Google Cloud Run.

1. Configure your project in deploy.bat:
   • Ensure your PROJECT_ID and REGION are set correctly.
2. Run the deployment script:

   deploy.bat
   

   The script will build the container image, push it to the Artifact Registry, and deploy it as a Cloud Run service.

Available Tools

This server exposes a suite of tools for interacting with GCS. For detailed information on each tool, its parameters, and return values, an agent can call the get_mcp_documentation tool.

A summary of tools can also be found in .

This README was generated by an AI agent.