mcp Documentation

Unknown repository by @google. Model Context Protocol (MCP) server & tools with 4.0k stars.

4,050 stars Unknown 1 file · ~43,157 tokens
RAW Doc

File: README.md

`google/mcp`

This repository contains a list of Google's official Model Context Protocol (MCP) servers, guidance on how to deploy MCP servers to Google Cloud, and examples to get started.

⚡ Google MCP Servers

**Remote MCP servers**

These remote MCP servers are managed by Google, and are available via endpoint. Below are a few key remote servrs. For a comprehensive list of all remote MCP servers managed by Google in General Availability (GA) and public preview vist the supported products pager

**Open-source MCP servers**

You can run these open-source MCP servers locally, or deploy them to Google Cloud (see below).

💻 Examples

  • Launch My Bakery (/examples/launchmybakery): A sample agent built with Agent Development Kit (ADK) that uses remote MCP servers for Google Maps and BigQuery.
  • Allstrides (/examples/allstrides): A sample app migrated from local to Cloud using remote MCP servers for Developer Knowledge, Cloud SQL and Cloud Run

📙 Resources

**Run an MCP server in Google Cloud**

🤝 Contributing

We welcome contributions to this repository, including bug reports, feature requests, documentation improvements, and code contributions. Please see our Contributing Guidelines to get started.

📃 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Disclaimers

This is not an officially supported Google product. This project is intended for demonstration purposes only.

This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.

File: examples/petpassport/README.md

Pet Passport: Pet-friendly route planner

This directory contains the Pet Passport application, a demo of an AI Agent using the Model Context Protocol (MCP) to combine data analysis and real-world location services.

Demo Overview

Pet Passport helps users plan a perfect day out with their dog based on breed popularity in New York City. The agent uses a "Macro-to-Micro" reasoning chain:

  1. Strategic Discovery (BigQuery): Identifies the NYC Zip Code with the highest population for a specific breed.
  2. Local Execution (Maps): Uses that Zip Code as a location bias to find "pet friendly cafes" and "dog parks".
  3. Itinerary Generation: Combines the data to create a "Pet Passport" itinerary.

The agent is built using the google-adk framework and powered by gemini-3.1.

Dataset

This demo uses the NYC Dog Licensing Dataset from NYC Open Data. It contains records of licensed dogs in New York City.

Project Structure

text
petpassport/
├── petpassport/
│   ├── __init__.py
│   ├── agent.py             # Agent definition using ADK
│   ├── tools.py             # MCP Tool configuration (BigQuery & Maps)
│   └── main.py              # FastAPI application exposing the agent
├── pyproject.toml           # Project dependencies
└── README.md                # This documentation

Prerequisites

  • Python 3.13+
  • Google Cloud Project with access to BigQuery and Maps MCP endpoints.
  • Environment Variables (Store these in a .env file in the project root):
    • MAPS_API_KEY: Your Google Maps API key.
    • GOOGLE_CLOUD_PROJECT: Your Google Cloud project ID.

Deployment Guide

Follow these steps to set up and run the demo.

1. Authenticate with Google Cloud

Set your active Google Cloud project and authenticate. This is required for the ADK to access BigQuery.

bash
gcloud config set project [YOUR-PROJECT-ID]
gcloud auth application-default login --project [YOUR-PROJECT-ID]

Note: If you encounter errors about a different project during authentication, you can bypass it by disabling the quota project and setting it manually:

bash
gcloud auth application-default login --disable-quota-project
gcloud auth application-default set-quota-project [YOUR-PROJECT-ID]

3. Configure Environment

Run the environment setup script. This script will:

  • Enable necessary Google Cloud APIs (Maps, BigQuery, remote MCP).
  • Create a restricted Google Maps Platform API Key.
  • Create a .env file with required environment variables.
bash
chmod +x setup/setup_env.sh
./setup/setup_env.sh

4. Provision BigQuery

Run the setup script. This script automates the following:

  • Creates a Cloud Storage bucket.
  • Uploads the CSV data files.
  • Creates the nyc_dogs BigQuery dataset.
  • Loads the data into BigQuery table licenses.
bash
chmod +x setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Installation

  1. Navigate to the project directory:

    bash
    cd examples/petpassport

  2. Create a virtual environment:

    bash
    python3 -m venv .venv

  3. Activate the virtual environment:

    bash
    source .venv/bin/activate

  4. Install dependencies:

    bash
    pip install google-adk==1.28.0 python-dotenv google-genai pillow

Running the Application Locally

To run the application locally on your machine:

  1. Install Uvicorn (if not already installed):

    bash
    pip install uvicorn

  2. Start the FastAPI server:

    bash
    uvicorn petpassport.main:app --reload

  3. Open the UI:
    Navigate to http://127.0.0.1:8000/ui/ in your browser to interact with the Pet Passport interface.

Sample prompt: "I have a Labrador Retriever. Where should we go in NYC?"

Deploying to Cloud Run

To deploy the Pet Passport agent to Google Cloud Run:

  1. Ensure you are in the project directory:

    bash
    cd examples/petpassport

  2. Deploy to Cloud Run:
    Use the following pure gcloud command to build and deploy the application to Cloud Run. Replace [YOUR-REGION] with your desired region (e.g., us-west1).

    bash
    gcloud run deploy petpassport \
  --source petpassport \
  --region [YOUR-REGION] \
  --allow-unauthenticated \
  --labels dev-tutorial=google-mcp

    Note: This command assumes you have the environment variables MAPS_API_KEY and GOOGLE_CLOUD_PROJECT set in your current shell.

  3. Permissions:
    Ensure the Cloud Run service account has the following IAM roles:

    • BigQuery Data Viewer and BigQuery Job User (to query BigQuery).
    • Storage Object Admin on the bucket pet-passport-data-$PROJECT_ID (to upload PDFs).

File: examples/launchmybakery/README.md

Launch My Bakery: Google remote MCP demo



This directory contains the data artifacts and infrastructure setup scripts for the MCP support for BigQuery & Google Maps demo.

Demo Overview

This scenario demonstrates an AI Agent's ability to orchestrate enterprise data (BigQuery) and real-world geospatial context (Google Maps) to solve a complex business problem:

"How would you help a friend launch a new high-end sourdough bakery in Los Angeles?"

The agent autonomously queries BigQuery to find macro trends and uses Google Maps to validate micro-location details. The demo relies on three key datasets:

  1. Demographics: To identify neighborhoods with high foot traffic using census data (Macro Discovery).
  2. Market Data: To analyze competitor pricing and suggest a premium price point (Pricing Strategy).
  3. Sales History: To forecast potential revenue based on comparable store trends (Forecasting).

Architecture Diagram

The diagram above illustrates the flow of information in this demo. The Agent, powered by Gemini 3.5 Flash, orchestrates requests between the user and Google Cloud services. It uses a remote (Google hosted) MCP server to securely access BigQuery for demographic and sales data, and Google Maps APIs for real-world location analysis and validation.

Repository Structure

text
launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
│   ├── demographics.csv
│   ├── bakery_prices.csv
│   ├── sales_history_weekly.csv
│   └── foot_traffic.csv
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       └── tools.py             # Custom tools for the agent
├── setup/                       # Infrastructure setup scripts
│   ├── setup_bigquery.sh        # Script to provision BigQuery dataset and tables
│   └── setup_env.sh             # Script to set up environment variables
├── cleanup/                     # Infrastructure clean up environment
│   ├── cleanup_env.sh           # Script to remove resources in environment
└── README.md                    # This documentation

Prerequisites

  • Google Cloud Project with billing enabled.
  • Google Cloud Shell (Recommended) or a local terminal with the gcloud CLI installed.

Deployment Guide

Follow these steps in Google Cloud Shell to provision the demo environment.

1. Clone the Repository

bash
git clone https://github.com/google/mcp.git
cd mcp/examples/launchmybakery

2. Authenticate with Google Cloud

Run the following command to authenticate with your Google Cloud account. This is required for the ADK to access BigQuery.

bash
gcloud config set project [YOUR-PROJECT-ID]
gcloud auth application-default login

Follow the prompts to complete the authentication process.

⚠️ Note: ADK does not automatically refresh your OAuth 2.0 token. If your chat session lasts more than 60 minutes, you may need to re-authenticate using the command above.

3. Configure Environment

Run the environment setup script. This script will:

  • Enable necessary Google Cloud APIs (Maps, BigQuery, remote MCP).
  • Create a restricted Google Maps Platform API Key.
  • Create a .env file with required environment variables.
bash
chmod +x setup/setup_env.sh
./setup/setup_env.sh

4. Provision BigQuery

Run the setup script. This script automates the following:

  • Creates a Cloud Storage bucket.
  • Uploads the CSV data files.
  • Creates the mcp_bakery BigQuery dataset.
  • Loads the data into BigQuery tables.
bash
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

5. Install ADK and Run Agent

Create a virtual environment, install the ADK, and run the agent.

bash
# Create virtual environment
python3 -m venv .venv

# If the above fails, you may need to install python3-venv:
# apt update && apt install python3-venv

# Activate virtual environment
source .venv/bin/activate

# Install ADK
pip install google-adk==1.28.0

# Navigate to the app directory
cd adk_agent/

# Run the ADK web interface
adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

6. Chat with the Agent

Open the link provided by adk web in your browser. You can now chat with the agent and ask it questions about the bakery data.

Sample Questions:

  • "I’m looking to open my fourth bakery location in Los Angeles. I need a neighborhood with early activity. Find the zip code with the highest 'morning' foot traffic score."
  • "Can you search for 'Bakeries' in that zip code to see if it's saturated? If there are too many, check for 'Specialty Coffee' shops, so I can position myself near them to capture foot traffic."
  • "Okay and I want to position this as a premium brand. What is the maximum price being charged for a 'Sourdough Loaf' in the LA Metro area?"
  • "Now I want a revenue projection for December 2025. Look at my sales history and take data from my best performing store for the 'Sourdough Loaf'. Run a forecast for December 2025 to estimate the quantity I'll sell. Then, calculate the projected total revenue using just under the premium price we found (let's use $18)"
  • "That'll cover my rent. Lastly, let's verify logistics. Find the closest "Restaurant Depot" to the proposed area and make sure that drive time is under 30 minutes for daily restocking."

To abort the ADK session in Cloud Shell, press Ctrl+C.

7. Cleanup

To avoid incurring ongoing costs for BigQuery storage or other Google Cloud resources, you can run the cleanup script. This script will delete the BigQuery dataset, the Cloud Storage bucket, and the API keys created during setup. Navigate back to the root directory of the repository and run the following command:

bash
chmod +x cleanup/cleanup_env.sh
./cleanup/cleanup_env.sh

Data Logic & Narratives

The data in this repository is synthetic but structured to support specific demo narratives and successful agent reasoning chains.

Table Demo Purpose Narrative Logic
foot_traffic Target DiscoveryFinding the target neighborhood. Morning activity is uniquely spiked in 90403, allowing the Agent to pinpoint it as the optimal location for a morning-focused business like a bakery.
demographics Community ProfilingAnalyzing market depth. Santa Monica (90403) is modeled with a dense, established residential population, providing a stable baseline for customer volume.
bakery_prices Pricing StrategySetting a price point. Erewhon Market has the highest price ceiling for a Sourdough Loaf (~$18.50), while the market average is ~$8.20. This allows the Agent to confidently suggest a premium price point of ~$15-18.
sales_history ForecastingPredicting growth. Silver Lake shows aggressive week-over-week growth trends, while Playa Vista represents a stable, high-volume flagship store, providing distinct patterns for forecasting models.

File: examples/allstrides/README.md

AllStrides: Google remote MCP for Cloud SQL and Developer Knowledge



This directory contains the data artifacts and infrastructure setup scripts for the Google remote MCP for Cloud SQL and Developer Knowledge demo.

Demo Overview

This scenario demonstrates an AI Agent's ability to act as a Product Architect, migrating a localized application to the cloud using Google Model Context Protocol (MCP) servers. By equipping Gemini CLI with access to Cloud SQL, Developer Knowledge and Cloud Run MCP, you can transform a manual deployment process into an agentic orchestration.

"How do I evolve AllStrides from a local-only prototype into a secure, globally accessible enterprise platform?"

Gemini CLI interacts with the Google Cloud ecosystem by leveraging three specific MCP servers to modernize the stack:

  1. Developer Knowledge MCP: To analyze the current application structure and identify the optimal Google Cloud database.
  2. Cloud SQL MCP: To provision a production-grade database instance and migrate local fitness community data to the cloud via a single natural language prompt.
  3. Cloud Run MCP: To containerize the allstrides application and deploy it to a serverless environment, making AllStrides live and accessible to users worldwide.

Architecture Diagram

This directory contains the sample application artifacts and a lab demonstrating how the MCP support for Developer Knowledge, Databases ad Cloud Run help to migrate demo application to the cloud.

Sample Application

The sample "Allstrides" application is featuring event management, fuser authentication, profile management, event CRUD operations, RSVP functionality, and real-time chat.

Architecture

This project is a Unified Full-Stack TypeScript Application.

  • Frontend: React (TypeScript)
  • Backend: Node.js / Express (TypeScript)
  • Database: SQLite (managed by Sequelize)
  • Real-time: WebSocket (ws)
  • Deployment: Single container serving both API and Static Frontend assets.

Project Structure

text
Listing: allstrides
├── frontend/
│   ├── public/
│   └── src/
│       ├── components/
│       │   ├── chat/
│       │   └── layout/
│       └── pages/
│           ├── auth/
│           ├── events/
│           └── profile/
└── server/
    └── src/
        ├── middleware/
        ├── models/
        └── routes/
  • frontend/: React application (CRA).
  • server/: Node.js/Express API and WebSocket server.
  • docker-compose.yml: Local deployment config.
  • start_allstrides.sh: Helper script for local execution.

Getting Started

Prerequisites

  • Node.js (v22 or later)
  • Docker (optional)

Configuration

The application listens on port 8080 by default. You can change this using:

  1. Environment Variable: PORT=3000 npm start
  2. Command Line Argument: npm start -- --port 3000

Running Locally

  1. Use the Helper Script:
    This script builds the frontend, sets up the server, and starts the application.

    bash
    ./start_allstrides.sh

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

  2. Manual Setup:

    Build Frontend:

    bash
    cd frontend
npm install
npm run build
cd ..

    Start Server:

    bash
    cd server
npm install
npm run build
npm start

Running with Docker

  1. Start the application:

    bash
    docker compose up --build

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

  2. Stop the application:

    bash
    docker compose down

Seeding the Database

You can populate the database with random test data using two methods:

Method 1: Scripted Seeding (Internal)
To use the internal Sequelize seed script (50 users, 200 events, 100 messages):

bash
cd server
npm run seed

Method 2: SQL Import (External)
To import the pre-generated SQLite script (50 users, 100 events from 2025-2026, 150 messages, and votes):

bash
# From the root of the 'allstrides' folder
sqlite3 allstrides.db < seed_data.sql

Note: This will overwrite existing data for users, events, messages, and votes.

Development Notes

  • Database: The application uses a local SQLite database (allstrides.db) located in the root allstrides folder (when running locally) or mapped to the container volume.
  • Authentication: Uses JWT. Passwords are hashed with BCrypt.
  • API Documentation: The backend endpoints are available at /api/....
  • Frontend Routing: The server is configured to handle client-side routing (SPA) by falling back to index.html for non-API routes.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →