Getting Started
Step 1 — Set Up Google API Credentials
You need credentials before configuring any client. Pick one method:
Option A — OAuth (Recommended — uses your own Google account)
- Go to Google Cloud Console and create or select a project
- Enable the Search Console API
- Go to Credentials → Create Credentials → OAuth client ID
- Configure the OAuth consent screen, select Desktop app, click Create
- Download the JSON file — save it somewhere permanent (e.g.
~/Documents/client_secrets.json)
On first use, a browser window will open asking you to sign in to your Google account. After that, the token is saved and no browser interaction is needed again.
Option B — Service Account (For automation or team use)
- Go to Google Cloud Console and create or select a project
- Enable the Search Console API
- Go to Credentials → Create Credentials → Service Account
- Go to the Keys tab → Add Key → Create new key → JSON → Download
- Save the file somewhere permanent (e.g.
~/Documents/service_account.json)
- Add the service account email to your GSC property: Search Console → Settings → Users and permissions → Add user → Full access
🎥 Watch the step-by-step setup tutorial for this section
Updated 2026 — covers the full installation process using the new uvx method, from setting up your Google credentials to your first successful query.
Step 2 — Installation
Option A — uvx (Recommended)
No cloning, no Python installation, no virtual environments. uvx downloads and runs the server automatically and keeps it up to date.
Install uv — open Terminal and run all three commands in order:
# 1. Download and install
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Activate in the current Terminal session
source $HOME/.local/bin/env
# 3. Make it permanent for all future sessions
echo 'source $HOME/.local/bin/env' >> ~/.zshrc
Verify:
uv --version
Why all three commands? The installer puts uv in ~/.local/bin, but your already-open Terminal session doesn't know about that folder yet. Step 2 activates it immediately. Step 3 ensures every future Terminal window has it automatically.
Now configure your AI client:
Claude Desktop
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json
OAuth:
{
"mcpServers": {
"gscServer": {
"command": "/FULL/PATH/TO/uvx",
"args": ["mcp-search-console"],
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
}
}
}
}
Service Account:
{
"mcpServers": {
"gscServer": {
"command": "/FULL/PATH/TO/uvx",
"args": ["mcp-search-console"],
"env": {
"GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
"GSC_SKIP_OAUTH": "true"
}
}
}
}
Cursor
Config file: ~/.cursor/mcp.json
OAuth:
{
"mcpServers": {
"gscServer": {
"command": "/FULL/PATH/TO/uvx",
"args": ["mcp-search-console"],
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
}
}
}
}
Codex CLI
Config file: ~/.codex/config.toml
OAuth:
[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/full/path/to/client_secrets.json" }
Service Account:
[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_CREDENTIALS_PATH = "/full/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }
Finding your uvx path: On macOS/Linux run which uvx in Terminal after installing uv (typically /Users/YOUR_NAME/.local/bin/uvx). On Windows, run Get-Command uvx | Select-Object -ExpandProperty Source in PowerShell (or where uvx in cmd) — it's usually C:\Users\YOUR_NAME\.local\bin\uvx.exe. Replace /FULL/PATH/TO/uvx in the configs above with that path.
Why the full path? GUI apps like Claude Desktop and Cursor launch without reading your shell config (~/.zshrc), so they don't know about ~/.local/bin. Using the full path guarantees it works regardless of how the app is launched. If you see a spawn uvx ENOENT error, this is the fix.
After saving the config, fully quit the app (Cmd+Q) and reopen it.
For OAuth: on first use, a browser window will open automatically for login. After that, the token is cached and you won't be asked again.
Option B — Clone (Advanced)
Prefer a video walkthrough for this method? The tutorial below covers the clone install path step by step — virtual environment setup, dependencies, and config:
Use this if you want to modify the code or run a specific local version. This method uses the video tutorial above for the credential setup steps.
Requires Python 3.11+. This server will not start on Python 3.10 or older — and when it's launched by a GUI client like Claude Desktop, it fails silently (no tools appear and no log file is written). Check your version with python --version. If it's below 3.11, install Python 3.11 or newer and recreate your virtual environment. The uvx method (Option A) avoids this entirely by managing the Python version for you, so it's the recommended path on Windows.
Clone the repo:
git clone https://github.com/AminForou/mcp-gsc.git
cd mcp-gsc
Or download the ZIP from the green Code button at the top of this page and unzip it.
Set up the environment:
uv venv .venv
uv pip install -r requirements.txt
Configure your AI client (Claude Desktop example):
OAuth:
{
"mcpServers": {
"gscServer": {
"command": "/full/path/to/mcp-gsc/.venv/bin/python",
"args": ["/full/path/to/mcp-gsc/gsc_server.py"],
"env": {
"GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
}
}
}
}
Service Account:
{
"mcpServers": {
"gscServer": {
"command": "/full/path/to/mcp-gsc/.venv/bin/python",
"args": ["/full/path/to/mcp-gsc/gsc_server.py"],
"env": {
"GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
"GSC_SKIP_OAUTH": "true"
}
}
}
}
Mac path examples:
- Python:
/Users/yourname/Documents/mcp-gsc/.venv/bin/python
- Script:
/Users/yourname/Documents/mcp-gsc/gsc_server.py
Step 3 — Test
Ask your AI assistant: "List my GSC properties"
If you see your properties — it's working. If not, ask: "Call get_capabilities" to see auth status and diagnose the issue.