Run MCP tools

This page shows you how to run a local agent and connect to a Data Commons MCP server running locally or remotely.

We provide specific instructions for the following agents:

  • Gemini CLI extension
    • Best for querying datacommons.org
    • Provides a built-in “agent” and context file for Data Commons
    • Downloads extension files locally
    • Uses uv to run the MCP server locally
    • Minimal setup

    See Use the Gemini CLI extension for this option.

  • Gemini CLI
    • Can be used for datacommons.org or a Custom Data Commons instance
    • No additional downloads
    • MCP server can be run locally or remotely
    • You can create your own context file
    • Minimal setup

    See Use Gemini CLI for this option.

  • A sample basic agent based on the Google Agent Development Kit
    • Best for interacting with a Web GUI
    • Can be used for datacommons.org or a Custom Data Commons instance
    • Can be customized to run other LLMs and prompts
    • Downloads agent code locally
    • Server may be run remotely
    • Some additional setup

    See Use the sample agent for this option.

For an end-to-end tutorial using a server and agent over HTTP, see the sample Data Commons Colab notebook, Try Data Commons MCP Tools with a Custom Agent.

For other clients/agents, see the relevant documentation; you should be able to reuse the commands and arguments detailed below.

Prerequisites

These are required for all agents:

Other requirements for specific agents are given in their respective sections.

Important: Additionally, for Custom Data Commons instances: If you have not rebuilt your Data Commons image since the stable release of 2025-09-08, you must sync to the latest stable release, rebuild your image and redeploy.

Configure environment variables

Base Data Commons (datacommons.org)

For basic usage against datacommons.org, set the required DC_API_KEY in your shell/startup script (e.g. .bashrc).

export DC_API_KEY=YOUR API KEY

Custom Data Commons

If you’re running a against a custom Data Commons instance, we recommend using a .env file, which the server locates automatically, to keep all the settings in one place. All supported options are documented in packages/datacommons-mcp/.env.sample.

To set variables using a .env file:

  1. From Github, download the file .env.sample to the desired directory. Or, if you plan to run the sample agent, clone the repo https://github.com/datacommonsorg/agent-toolkit/.

  2. From the directory where you saved the sample file, copy it to a new file called .env. For example: 
    cd ~/agent-toolkit/packages/datacommons-mcp
cp .env.sample .env
  3. Set the following variables:
    • DC_API_KEY: Set to your Data Commons API key
    • DC_TYPE: Set to custom.
    • CUSTOM_DC_URL: Uncomment and set to the URL of your instance.
  4. Optionally, set other variables.
  5. Save the file.

Use the Gemini CLI extension

Additional prerequisites In addition to the standard prerequisites, you must have the following installed:

When you install the extension, it clones the Data Commons extension Github repo to your local system.

Install

Open a new terminal and install the extension directly from GitHub:

gemini extensions install https://github.com/gemini-cli-extensions/datacommons [--auto-update]

Note: If you have previously configured Gemini CLI to use the Data Commons MCP Server and want to use the extension instead, be sure to delete the datacommons-mcp section from the relevant settings.json file (e.g. ~/.gemini/settings.json).

Run

  1. From any directory, run gemini.
  2. To verify that the Data commons tools are running, enter /mcp list. You should see datacommons-mcp listed as Ready. If you don’t, see the Troubleshoot section.
  3. To verify that the extension is running, enter /extensions list. You should see datacommons listed as active.
  4. Start sending natural-language queries.

Update

After starting up Gemini CLI, you may see the message You have one extension with an update available.

In this case, run /extensions list. If datacommons is displayed with update available, enter the following in the Gemini input field:

/extensions update datacommons

Troubleshoot

You can diagnose common errors, such as invalid API keys, by using the debug flag:

gemini -d

You can also use the Ctrl-o option from inside the Gemini input field.

Here are solutions to some commonly experienced problems.

Install/update/uninstall hangs and does not complete

  1. Check that you are not running the gemini extensions command from inside the Gemini input field. Start a new terminal and run it from the command line.
  2. Check that you’ve spelled commands correctly, e.g. extensions and not extension.

datacommons-mcp is disconnected

This is usually due to a missing Data Commons API key. Be sure to obtain a key and export it on the command line or in a startup script (e.g. .bashrc). If you’ve exported it in a startup script, be sure to start a new terminal.

Failed to clone Git repository

Make sure you have installed Git on your system.

Uninstall

To uninstall the extension, run:

gemini extensions uninstall datacommons

Use Gemini CLI

Before installing, be sure to check the Prerequisites above.

Install

To install Gemini CLI, see the instructions at https://github.com/google-gemini/gemini-cli#quick-install.

Configure to run a local server

To configure Gemini CLI to recognize the Data Commons server, edit the relevant settings.json file (e.g. ~/.gemini/settings.json) to add the following:

{
   // ...
    "mcpServers": {
       "datacommons-mcp": {
           "command": "uvx",
            "args": [
                "datacommons-mcp@latest",
                "serve",
                "stdio"
            ],
            "env": {
                "DC_API_KEY": "YOUR_DATA_COMMONS_API_KEY"
                // If you are using a Google API key
                "GEMINI_API_KEY": "YOUR_GOOGLE_API_KEY"
            },
            "trust": true
        }
    }
   // ...
}

Configure to connect to a remote server

  1. Start up the MCP server in standalone mode, as described in Run a standalone server.
  2. In the settings.json file, replace the datacommons-mcp specification as follows: 
    {
 "mcpServers": {
     "datacommons-mcp": {
         "httpUrl": "http://HOST:PORT/mcp"
         // other settings as above
      }
   }
}

Send queries

  1. From any directory, run gemini.
  2. To see the Data Commons tools, use /mcp tools.
  3. Start sending natural-language queries.

Tip: To ensure that Gemini CLI uses the Data Commons MCP tools, and not its own GoogleSearch tool, include a prompt to use Data Commons in your query. For example, use a query like “Use Data Commons tools to answer the following: …” You can also add such a prompt to a GEMINI.md file so that it’s persisted across sessions.

Use the sample agent

We provide a basic agent for interacting with the MCP Server in packages/datacommons-mcp/examples/sample_agents/basic_agent.

Additional prerequisites In addition to the standard prerequisites, you will need:

Set the API key environment variable

Set GEMINI_API_KEY (or GOOGLE_API_KEY) in your shell/startup script (e.g. .bashrc):

export GEMINI_API_KEY=YOUR API KEY

Install

From the desired directory, clone the agent-toolkit repo:

git clone https://github.com/datacommonsorg/agent-toolkit.git

Run

By default, the agent will spawn a local server and connect to it over Stdio. If you want to connect to a remote server, modify the code as described in Connect to a remote server before using this procedure.

  1. Go to the root directory of the repo: 
    cd agent-toolkit
  2. Run the agent using one of the following methods.
  1. Run the following command: 
    uvx --from google-adk adk web ./packages/datacommons-mcp/examples/sample_agents/
  2. Point your browser to the address and port displayed on the screen (e.g. http://127.0.0.1:8000/). The Agent Development Kit Dev UI is displayed.
  3. From the Type a message box, type your query for Data Commons or select another action.

Command line interface

  1. Run the following command: 
    uvx --from google-adk adk run ./packages/datacommons-mcp/examples/sample_agents/basic_agent
  2. Enter your queries at the User prompt in the terminal.

Configure to connect to a remote server

If you want to connect to a remote MCP server, follow this procedure before starting the agent:

  1. Start up the MCP server in standalone mode, as described in Run a standalone server.
  2. Modify the code in basic_agent/agent.py to set import modules and agent initialization parameters as follows:
from google.adk.tools.mcp_tool.mcp_toolset import (
   MCPToolset,
   StreamableHTTPConnectionParams
)

root_agent = LlmAgent(
      # ...
      tools=[McpToolset(
         connection_params=StreamableHTTPConnectionParams(
            url=f"http://<host>:<port>/mcp"
         )
      )],
   )

Sample queries

The Data Commons MCP tools excel at natural-language queries that involve:

  • Comparisons between two or more entities, such as countries or metrics
  • Exploring data available for a given topic

Here are some examples of such queries:

  • “What health data do you have for Africa?”
  • “What data do you have on water quality in Zimbabwe?”
  • “Compare the life expectancy, economic inequality, and GDP growth for BRICS nations.”
  • “Generate a concise report on income vs diabetes in US counties.”

Run a standalone server

  1. Ensure you’ve set up the relevant server environment variables. If you’re using a .env file, go to the directory where the file is stored.
  2. Run: 
    uvx datacommons-mcp serve http [--host HOSTNAME] [--port PORT]

    By default, the host is localhost and the port is 8080 if you don’t set these flags explicitly.

The server is addressable with the endpoint mcp. For example, http://my-mcp-server:8080/mcp.

You can connect to the server using Gemini CLI or the sample ADK agent. If you’re using a different client from the ones documented on this page, consult its documentation to determine how to specify an HTTP URL.

Page last updated: November 11, 2025 • Send feedback about this page