DEV Community

Google Developer Experts profile image xbill
xbill for Google Developer Experts

Posted on • Originally published at Medium on

Firestore MCP Development with Ruby, Cloud Run, and Gemini CLI

#ruby #mcps #gemini #googlecloudrun

Leveraging Gemini CLI and the underlying Gemini LLM to build Model Context Protocol (MCP) AI applications with Ruby deployed to Google Cloud Run backed by a Firestore NOSQL database.


Image by Author

Why not just use Python?

Python has traditionally been the main coding language for ML and AI tools. One of the strengths of the MCP protocol is that the actual implementation details are independent of the development language. The reality is that not every project is coded in Python- and MCP allows you to use the latest AI approaches with other coding languages.

Ruby? For AI? Is this even possible?

The goal of this article is to provide a minimal viable basic working MCP stdio server in Ruby that can be run locally without any unneeded extra code or extensions. The official Ruby MCP SDK is here:

GitHub - modelcontextprotocol/ruby-sdk: The official Ruby SDK for the Model Context Protocol. Maintained in collaboration with Shopify.

What Is Ruby?

Ruby is a dynamic, general-purpose programming language known for its focus on simplicity and developer happiness. It is an open-source, object-oriented language that aims for an elegant syntax which is natural to read and easy to write, almost like English.

The full details of the language can be found here:

Ruby Programming Language

What is Ruby Gems?

RubyGems is a package manager for the Ruby programming language that provides a standard format for distributing Ruby programs and libraries.

The main download site is here:

RubyGems.org | your community gem host

Ruby Version Management

One of the downsides of the wide deployment of Ruby has been managing the language versions across platforms and maintaining a supported version. There are several Ruby version managers- a good starting point is rvm :

RVM: Ruby Version Manager - RVM Ruby Version Manager - Documentation

Install rvm :

xbill@penguin:~$ gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D69
56105BD0E739499BDB
gpg: directory '/home/xbill/.gnupg' created
gpg: keybox '/home/xbill/.gnupg/pubring.kbx' created
gpg: key 105BD0E739499BDB: 2 duplicate signatures removed
gpg: /home/xbill/.gnupg/trustdb.gpg: trustdb created
gpg: key 105BD0E739499BDB: public key "Piotr Kuczynski <piotr.kuczynski@gmail.com>" imported
gpg: key 3804BB82D39DC0E3: public key "Michal Papis (RVM signing) <mpapis@gmail.com>" imported
gpg: Total number processed: 2
gpg: imported: 2
xbill@penguin:~$ \curl -sSL https://get.rvm.io | bash -s stable
Downloading https://github.com/rvm/rvm/archive/1.29.12.tar.gz
Downloading https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz.asc
gpg: Signature made Fri 15 Jan 2021 01:46:22 PM EST
gpg: using RSA key 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
gpg: Good signature from "Piotr Kuczynski <piotr.kuczynski@gmail.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7D2B AF1C F37B 13E2 069D 6956 105B D0E7 3949 9BDB
GPG verified '/home/xbill/.rvm/archives/rvm-1.29.12.tgz'
Installing RVM to /home/xbill/.rvm/
    Adding rvm PATH line to /home/xbill/.profile /home/xbill/.mkshrc /home/xbill/.bashrc /home/xbill/.zshrc.
    Adding rvm loading line to /home/xbill/.profile /home/xbill/.bash_profile /home/xbill/.zlogin.
Installation of RVM in /home/xbill/.rvm/ is almost complete:
Enter fullscreen mode Exit fullscreen mode

Then download the latest Ruby- as of writing it is 3.4.8:

xbill@penguin:~$ source /home/xbill/.rvm/scripts/rvm
xbill@penguin:~$ rvm install 3.4.8
Searching for binary rubies, this might take some time.
No binary rubies available for: debian/12/x86_64/ruby-3.4.8.
Continuing with compilation. Please read 'rvm help mount' to get more information on binary rubies.
Checking requirements for debian.
Installing requirements for debian.
Updating system....
Enter fullscreen mode Exit fullscreen mode

What is Firestore?

Google Firestore, also known as Cloud Firestore is a part of the Google Firebase application development platform. It is fundamentally a cloud-hosted NoSQL database for storing and syncing data. Firestore can be directly accessed by mobile and web applications through native SDKs.

Firestore | Firebase

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli
Enter fullscreen mode Exit fullscreen mode

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

gemini
Enter fullscreen mode Exit fullscreen mode

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Ruby MCP Documentation

The official MCP GitHub Repo provides samples and documentation for getting started:

ruby-sdk/README.md at main · modelcontextprotocol/ruby-sdk

Where do I start?

The strategy for starting MCP development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal Hello World Style Ruby MCP Server is built with HTTP transport. This server is validated with Gemini CLI in the local environment.

This setup validates the connection from Gemini CLI to the local process via MCP. The MCP client (Gemini CLI) and the Ruby MCP server both run in the same local environment.

Next- the basic MCP server is wrapped in a container and deployed to Google Cloud Run. The remote endpoint is validated with a local copy of Gemini CLI running as a MCP client.

Setup the Basic Environment

At this point you should have a working Ruby environment and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts:

cd ~
git clone https://github.com/xbill9/gemini-cli-codeassist
Enter fullscreen mode Exit fullscreen mode

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

cd gemini-cli-codeassist
source init.sh
Enter fullscreen mode Exit fullscreen mode

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

cd gemini-cli-codeassist
source set_env.sh
Enter fullscreen mode Exit fullscreen mode

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Hello World with HTTP Transport

One of the key features that the standard MCP libraries provide is abstracting various transport methods.

The high level MCP tool implementation is the same no matter what low level transport channel/method that the MCP Client uses to connect to a MCP Server.

The simplest transport that the SDK supports is the stdio (stdio/stdout) transport — which connects a locally running process. Both the MCP client and MCP Server must be running in the same environment.

The HTTP transport allows the client and server to run in the same environment or be distributed over the Internet.

The connection over HTTP will look similar to this:

# Create the Fixed Streamable HTTP transport
transport = FixedStreamableHTTPTransport.new(server)
server.transport = transport
Enter fullscreen mode Exit fullscreen mode

Gemfile

The Ruby Gemfile includes the MCP and logging gems:

  spec.name = 'firestore-https-ruby'
  spec.version = '0.1.0'
  spec.authors = ['xbill']
  spec.email = ['xbill9@gmail.com']

  spec.summary = 'A Model Context Protocol (MCP) server for Google Cloud Firestore.'
  spec.description = 'Exposes Firestore operations (inventory management) as MCP tools over stdio.'
  spec.homepage = 'https://github.com/xbill9/gemini-cli-codeassist/firestore-https-ruby'
  spec.license = 'MIT'
  spec.required_ruby_version = '>= 3.1.0'
Enter fullscreen mode Exit fullscreen mode

Running the Ruby Code

First- switch the directory with the Ruby MCP sample code:

cd ~/gemini-cli-codeassist/firestore-https-ruby
Enter fullscreen mode Exit fullscreen mode

Run the install make target on the local system:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make install
Installing dependencies...
Bundle complete! 10 Gemfile dependencies, 61 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
1 installed gem you directly depend on is looking for funding.
  Run `bundle fund` for details
Enter fullscreen mode Exit fullscreen mode

To test the Ruby code:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make test
Running tests...
{"timestamp":"2026-01-07T19:40:15-05:00","level":"INFO","message":"Firestore client initialized"}
..

Finished in 0.00416 seconds (files took 0.65313 seconds to load)
2 examples, 0 failures
Enter fullscreen mode Exit fullscreen mode

To style check / lint the code:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make lint
Linting the code...
Inspecting 12 files
............

12 files inspected, no offenses detected
xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$
Enter fullscreen mode Exit fullscreen mode

Gemini CLI settings.json

The default Gemini CLI settings.json has an entry for the Ruby source:

 {
    "mcpServers": {
    "firestore-https-ruby": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Review the Project with Gemini CLI

Start-up Gemini CLI and review the entire project:

> what does this project do?

✦ This project is a Ruby-based Model Context Protocol (MCP) server that provides a set of tools to interact with a Google Cloud
  Firestore database.

  Core Functionality
  It manages a retail inventory system (the inventory collection) and exposes the following tools via a streaming HTTP
  transport:
   * Inventory Management: Seed the database with sample data (seed), clear all items (reset), and list all products
     (get_products).
   * Product Lookup: Retrieve specific product details by their ID (get_product_by_id).
   * System Health: Check database connectivity (check_db) and get a server greeting (get_root).

  Key Components
   * Language: Ruby using the mcp SDK.
   * Database: Google Cloud Firestore.
   * Server: Puma (Rack-compatible) configured for HTTP streaming.
   * Structure: Individual tool logic is modularized in lib/mcp_server/tools/, with main.rb acting as the server entry point.

  It is designed to be connected to MCP clients (like Claude Desktop or other AI agents) to allow them to programmatically
  manage and query the inventory database.
Enter fullscreen mode Exit fullscreen mode

Start the Local HTTP server

Start a terminal window and use the run target in the Makefile:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make run
Running the application...
{"timestamp":"2026-01-07T18:59:43-05:00","level":"INFO","message":"Firestore client initialized"}
{"timestamp":"2026-01-07T18:59:43-05:00","level":"INFO","message":"Starting MCP server: inventory-server (v1.0.0) on HTTP port 8080"}
Puma starting in single mode...
* Puma version: 7.1.0 ("Neon Witch")
* Ruby version: ruby 3.4.8 (2025-12-17 revision 995b59f666) +PRISM [x86_64-linux]
* Min threads: 0
* Max threads: 5
* Environment: development
* PID: 19919
* Listening on http://0.0.0.0:8080
Use Ctrl-C to stop
{"timestamp":"2026-01-07T18:59:50-05:00","level":"INFO","type":"request","method":"POST","path":"/mcp","status":200,"remote_addr":"127.0.0.1"}
{"timestamp":"2026-01-07T18:59:50-05:00","level":"INFO","type":"request","method":"POST","path":"/mcp","status":202,"remote_addr":"127.0.0.1"}
Enter fullscreen mode Exit fullscreen mode

Validation with Gemini CLI

Start a new window with Gemini CLI to validate the MCP connection over HTTP to the Ruby Code:

gemini

> /mcp list

Configured MCP servers:

🟢 firestore-https-ruby - Ready (6 tools)
  Tools:
  - check_db
  - get_product_by_id
  - get_products
  - get_root
  - reset
  - seed

> get_products

✦ I will now retrieve the list of all products from the inventory database.

╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ? get_products (firestore-https-ruby MCP Server) {} ← │
│ │
│ MCP Server: firestore-https-ruby │
│ Tool: get_products │
│ │
│ Allow execution of MCP tool "get_products" from server "firestore-https-ruby"? │
│ │
│ 1. Allow once │
│ 2. Allow tool for this session │
│ ● 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ Products retrieved. What would you like to do next?

> summarize the products

✦ There are 34 products in the inventory, ranging in price from $1 to $10. Stock levels vary significantly, with items like Eggs
  and Bananas having nearly 500 units, while others like Wasabi Party Mix and Jalapeno Seasoning are currently out of stock. The
  inventory includes a variety of categories such as produce, dairy, snacks, and beverages.
Enter fullscreen mode Exit fullscreen mode

Deploying to Cloud Run

After the HTTP version of the MCP server has been tested locally — it can be deployed remotely to Google Cloud Run.

First- switch to the directory with the HTTP MCP sample code:

cd ~/gemini-cli-codeassist/firestore-https-ruby
Enter fullscreen mode Exit fullscreen mode

Deploy the project to Google Cloud Run with the pre-built cloudbuild.yaml and Dockerfile:

cd ~/gemini-cli-codeassist/firestore-https-ruby
xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make deploy
Enter fullscreen mode Exit fullscreen mode

The Cloud Build will start:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ make deploy
gcloud builds submit . --config cloudbuild.yaml
Creating temporary archive of 22 file(s) totalling 27.1 KiB before compression.
Some files were not included in the source upload.

Check the gcloud log [/home/xbill/.config/gcloud/logs/2026.01.07/19.46.43.736456.log] to see which files and the contents of the
default gcloudignore file used (see `$ gcloud topic gcloudignore` to learn
more).

Uploading tarball of [.] to [gs://comglitn_cloudbuild/source/1767833213.603108-18114194f18b41a5960c00a568290741.tgz]
Created [https://cloudbuild.googleapis.com/v1/projects/comglitn/locations/global/builds/afe53c21-248c-4ef1-9193-b2494d68e48f].
Logs are available at [https://console.cloud.google.com/cloud-build/builds/afe53c21-248c-4ef1-9193-b2494d68e48f?project=1056842563084].
Waiting for build to complete. Polling interval: 1 second(s).
Enter fullscreen mode Exit fullscreen mode

It can take 5–10 minutes to complete the build.

When the build is complete- an endpoint will be returned:

Starting Step #2
Step #2: Already have image (with digest): gcr.io/cloud-builders/gcloud
Step #2: Deploying container to Cloud Run service [firestore-https-ruby] in project [comglitn] region [us-central1]
Step #2: Deploying...
Step #2: Setting IAM Policy.........done
Step #2: Creating Revision...........................................................................................................................................................................................................................................................................done
Step #2: Routing traffic.....done
Step #2: Done.
Step #2: Service [firestore-https-ruby] revision [firestore-https-ruby-00003-hqv] has been deployed and is serving 100 percent of traffic.
Step #2: Service URL: https://firestore-https-ruby-1056842563084.us-central1.run.app
Enter fullscreen mode Exit fullscreen mode

The service endpoint in this example is :

https://mcp-https-ruby-1056842563084.us-central1.run.app
Enter fullscreen mode Exit fullscreen mode

The actual endpoint will vary based on your project settings.

Review Service in Cloud Run

Navigate to the Google Cloud console and search for Cloud Run -

and then you can detailed information on the Cloud Run Service:

Cloud Logging

The remote server writes logs to stderr in standard JSON format. These logs are available from the deployed Cloud Run Service:

Validate HTTP connection

Once you have the Endpoint — you can attempt a connection- navigate to in your browser:

https://firestore-https-ruby-1056842563084.us-central1.run.app
Enter fullscreen mode Exit fullscreen mode

You will need to adjust the exact URL to match the URL returned from Cloud Build.

You will get an error- this connection is expecting a message in the MCP format:

Not Found
Enter fullscreen mode Exit fullscreen mode

Gemini CLI settings.json.cloudrun

Replace the default Gemini CLI configuration file —  settings.json with a pre-configured sample- settings.json.cloudrun to use the Cloud Run version of the connection:

 {
    "mcpServers": {
    "firestore-cloudrun-ruby": {
      "httpUrl": "https://firestore-https-ruby-$PROJECT_NUMBER.us-central1.run.app/mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Copy the Cloud Run version of the Gemini CLI configuration file:

xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby$ cd .gemini
cp settings.json.cloudrun settings.json
xbill@penguin:~/gemini-cli-codeassist/firestore-https-ruby/.gemini$
Enter fullscreen mode Exit fullscreen mode

Validation with Gemini CLI

The final connection test uses Gemini CLI as a MCP client with the deployed Cloud Run Service in Ruby providing the MCP server. Startup Gemini CLI with the updated settings :

gemini

> /mcp list

Configured MCP servers:

🟢 firestore-cloudrun-ruby - Ready (6 tools)
  Tools:
  - check_db
  - get_product_by_id
  - get_products
  - get_root
  - reset
  - seed

✦ I'll fetch the list of products from the inventory database for you.
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ? get_products (firestore-cloudrun-ruby MCP Server) {} ← │
│ │
│ MCP Server: firestore-cloudrun-ruby │
│ Tool: get_products │
│ │
│ Allow execution of MCP tool "get_products" from server "firestore-cloudrun-ruby"? │
│ │
│ ● 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ 4. No, suggest changes (esc) │
│ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ I have retrieved the list of products from the inventory. How would you like to proceed?

> summarize products by category

✦ Based on the products currently in the inventory, I've categorized them as follows:

  Produce
   - Apples ($3, Qty: 423)
   - Bananas ($4, Qty: 494)
   - Watermelon ($7, Qty: 279)
   - Broccoli ($2, Qty: 93)

  Dairy & Eggs
   - Milk ($4, Qty: 62)
   - Eggs ($1, Qty: 496)
   - Cheddar Cheese ($6, Qty: 132)
   - Yogurt ($1, Qty: 416)

  Bakery & Grains
   - Whole Wheat Bread ($10, Qty: 328)
   - Rice ($2, Qty: 296)
   - Jasmine Rice ($4, Qty: 167)
   - Smores Cereal ($6, Qty: 23)

  Meat & Seafood
   - Whole Chicken ($10, Qty: 200)
   - Beef ($10, Qty: 238)
   - Shrimp ($4, Qty: 408)

  Pantry & Snacks
   - Black Beans ($3, Qty: 486)
   - Walnuts ($7, Qty: 2)
   - Sunflower Seeds ($2, Qty: 349)
   - Fresh Basil ($8, Qty: 81)
   - Cinnamon ($3, Qty: 25)
   - Parmesan Crisps ($2, Qty: 363)
   - Mint Chocolate Cookies ($9, Qty: 215)
   - White Chocolate Caramel Corn ($4, Qty: 430)
   - Peanut Butter and Jelly Cups ($3, Qty: 2)
   - Wasabi Party Mix ($7, Qty: 0 - Out of Stock)
   - Jalapeno Seasoning ($1, Qty: 0 - Out of Stock)
   - Maple Almond Butter ($5, Qty: 471)
   - Coffee Beans ($6, Qty: 375)

  Beverages
   - Bottled Water ($5, Qty: 319)
   - Apple Juice ($5, Qty: 4)
   - Cola ($10, Qty: 93)
   - Green Tea ($6, Qty: 474)
   - Pineapple Kombucha ($8, Qty: 402)
   - Acai Smoothie Packs ($4, Qty: 109)
Enter fullscreen mode Exit fullscreen mode

Summary

MCP development with Ruby using Gemini CLI was validated with an incremental step by step approach.

A minimal streaming HTTP transport MCP Server was built from source code and validated with Gemini CLI running as a MCP client in the same local environment.

Then — the MCP server was wrapped in a container and submitted to Google Cloud Build for deployment to Google Cloud Run. The remote MCP server was validated with a standard browser, and Gemini CLI.

Finally- remote MCP operations were performed from the local Gemini CLI installation to the Ruby MCP server hosted in Google Cloud Run.

This approach can be extended to more complex deployments and Cloud based options.

Top comments (0)