Installation and MCP client setup

This guide installs the published gsc-mcp-tools package, connects only the providers you use, and verifies the 81-tool registry. Python 3.11 or newer is required.

Choose an installation mode

Use case	Command	Upgrade path
Persistent MCP client	uv tool install gsc-mcp-tools	uv tool upgrade gsc-mcp-tools
One-time evaluation	uvx gsc-mcp-tools	Resolved on each launch
Existing Python environment	pip install gsc-mcp-tools	pip install --upgrade gsc-mcp-tools
Contributor checkout	pip install -e ".[dev]"	Pull the repository and reinstall if metadata changes

For Codex and Claude Desktop, prefer the persistent uv tool installation. Pointing the client at the installed executable avoids an extra uvx launcher process for every active MCP server.

Install the published package with uv

Install uv first, then run:

uv tool install gsc-mcp-tools
command -v gsc-mcp-tools
gsc-cli list

gsc-cli list should print 81 commands for release 1.2.0. Keep the absolute path returned by command -v; MCP clients do not always inherit the same PATH as your shell.

Upgrade later with:

uv tool upgrade gsc-mcp-tools

An installation created with gsc-mcp-tools==1.2.0 stays pinned. Reinstall without the version constraint before using uv tool upgrade, or install the next explicit version with --force.

To reproduce this release exactly:

uv tool install --force gsc-mcp-tools==1.2.0

Alternative installations

Run once with uvx

uvx gsc-mcp-tools

This is useful for evaluation. Do not use it as the persistent client command when you want the smallest process footprint.

Install in a Python virtual environment

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install gsc-mcp-tools
gsc-cli list

Use the absolute .venv/bin/gsc-mcp-tools path in the MCP client configuration.

Install a source checkout for development

git clone https://github.com/FlorianBruniaux/google-search-console-mcp
cd google-search-console-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest -q
gsc-cli list

Use this mode only when developing or testing changes that are not yet published.

Configure provider credentials

Install the server once, then add only the credentials required by the provider families you use.

Provider	Configuration	Required variable
Google Search Console	Google setup	GSC_SERVICE_ACCOUNT_PATH, or GSC_CREDENTIALS_PATH plus an interactive OAuth login
Google Analytics 4	Google setup	GA4_PROPERTY_ID plus Google credentials
Chrome UX Report	Enable the CrUX API and create a Google API key	CRUX_API_KEY
Bing Webmaster Tools	Bing setup	BING_WEBMASTER_API_KEY
IndexNow	Verify a key on each target host	Key passed explicitly to indexnow_submit

Do not put API keys in prompts or tool arguments unless the tool contract explicitly requires one. BING_WEBMASTER_API_KEY belongs in the server environment. The Bing Webmaster key and the per-host IndexNow key are different credentials.

Codex setup without global process proliferation

Codex starts one stdio MCP server for each task that loads it. Keep the complete definition disabled in the private user configuration, then enable it only in projects that need search data.

Add this to ~/.codex/config.toml:

[mcp_servers.gsc-mcp]
command = "/absolute/path/to/gsc-mcp-tools"
enabled = false
startup_timeout_sec = 60
tool_timeout_sec = 90

[mcp_servers.gsc-mcp.env]
GSC_SERVICE_ACCOUNT_PATH = "/absolute/path/to/service-account.json"
GSC_SKIP_OAUTH = "true"
GA4_PROPERTY_ID = "123456789"
CRUX_API_KEY = "<from-your-secret-store>"
BING_WEBMASTER_API_KEY = "<from-your-secret-store>"

Remove every provider variable you do not use. This user-level file is private but still contains sensitive values, so keep its permissions restricted.

In each trusted project that needs the server, create .codex/config.toml:

[mcp_servers.gsc-mcp]
enabled = true

Add .codex/config.toml to the project .gitignore, restart the task, then verify from that project:

codex mcp get gsc-mcp

The resolved configuration should show enabled: true and the direct executable path. Outside an enabled project, the same command should show the server as disabled.

Claude Desktop setup

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "/absolute/path/to/gsc-mcp-tools",
      "env": {
        "GSC_SERVICE_ACCOUNT_PATH": "/absolute/path/to/service-account.json",
        "GSC_SKIP_OAUTH": "true",
        "GA4_PROPERTY_ID": "123456789",
        "CRUX_API_KEY": "<from-your-secret-store>",
        "BING_WEBMASTER_API_KEY": "<from-your-secret-store>"
      }
    }
  }
}

Remove unused variables and restart Claude Desktop. Saving the JSON file does not restart an existing MCP process.

Verify the installation

Run these checks from the same environment used by the MCP client:

gsc-cli list
gsc-cli get-capabilities

list verifies package and registry loading. get-capabilities reports declared credential families; it does not prove that an external API accepts them. Verify provider access separately with list-properties for Google or bing-sites-list for Bing.

Troubleshooting

The client launches an older release: run uv tool list, then uv tool upgrade gsc-mcp-tools. If the receipt is pinned, reinstall without ==....

PyPI has the release but uv cannot resolve it immediately: retry from outside the source checkout with an explicit refresh:

uv tool install --force --refresh --default-index https://pypi.org/simple gsc-mcp-tools

The client cannot find the executable: use the absolute path returned by command -v gsc-mcp-tools.

Many uvx and server processes remain: replace uvx gsc-mcp-tools with the persistent executable, disable the user-level Codex server, enable it only per project, then fully restart the client. Existing processes keep their old configuration until they exit.