Skip to main content
Glama
modelbrain-search-console

modelbrain-search-console

Official
README.md
# ModelBrain free connectors

Hosted, read-only MCP connectors from [ModelBrain](https://modelbrain.net/). Free for every account and every property.

First connector: **ModelBrain Search Console** at `https://gsc.modelbrain.net/mcp`.

## Tools (Search Console)

| Tool | What it returns |
|---|---|
| `list_sites` | Every property the Google account can see, with permission level |
| `search_performance` | Clicks, impressions, CTR, position by query, page, country, device, date or search appearance, with filters and paging (up to 25,000 rows a call, 16 months) |
| `inspect_url` | Index status, coverage, last crawl, canonical, robots and rich results for one URL |
| `list_sitemaps` | Submitted sitemaps with last read, errors, warnings and URL counts |
| `compare_periods` | Two date ranges side by side, plus the biggest risers and fallers |

Every tool is marked `readOnlyHint: true`. The only Google scope requested is `webmasters.readonly`.

## How sign-in works

1. The AI app registers itself (`/register`, RFC 7591) and sends the person to `/authorize` with a PKCE S256 challenge.
2. We send them to Google, asking for `openid` and the one read-only scope, with offline access.
3. Google returns to `/oauth/google/callback`. We read the account ID from the ID token, seal the Google refresh token with ChaCha20-Poly1305 and store it.
4. The app swaps a one-time code at `/token` for our own access token (1 hour) and refresh token (90 days, rotated on use).

## What is stored

- Google account ID and the sealed Google refresh token.
- SHA-256 hashes of our own codes and tokens.
- Registered app names and redirect addresses.

Search data passes straight through and is never stored. Logs hold method, tool name, outcome and duration only. No email addresses are kept.

## Configuration

| Variable | Meaning |
|---|---|
| `CONNECTOR` | `gsc` (default) |
| `BASE_URL` | Public address, for example `https://gsc.modelbrain.net` |
| `BIND` | Listen address, default `0.0.0.0:8787` |
| `DB_PATH` | SQLite file, default `connectors.db` |
| `GOOGLE_OAUTH_JSON_FILE` | Path to the client JSON downloaded from Google Cloud (or set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, each also as `*_FILE`) |
| `TOKEN_KEY` / `TOKEN_KEY_FILE` | 32 random bytes, base64 (`openssl rand -base64 32`). Losing it signs everyone out. |
| `EXTRA_REDIRECT_HOSTS` | Comma-separated extra https hosts allowed as app callbacks |
| `CALLS_PER_MINUTE` | Per-account tool call limit, default 60 |
| `RUST_LOG` | Log filter, default `info` |

## Local run

```sh
export BASE_URL=http://localhost:8787
export GOOGLE_OAUTH_JSON_FILE=$HOME/path/to/client_secret.json
export TOKEN_KEY=$(openssl rand -base64 32)
cargo run --release
```

Then add `http://localhost:8787/mcp` as a connector in an MCP client that allows localhost, or test with the MCP Inspector.

## Tests

```sh
cargo test
cargo clippy --all-targets -- -D warnings
```

## Security

- The code that handles your Google access is all here: sign-in in `src/oauth.rs`, token sealing in `src/crypto.rs`, storage in `src/store.rs`.
- The connector asks Google only for `webmasters.readonly`. It cannot change anything in Search Console.
- You can remove its access at any time at https://myaccount.google.com/permissions. The connector then drops every token it issued for your account.
- Report a security problem privately to security@modelbrain.net rather than in a public issue.

## License

MIT. See [LICENSE](LICENSE). "ModelBrain" is a trademark of Matthew Firth; the license covers the code, not the name or logo.

TDQS

A4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a clearly distinct resource or operation: property enumeration (list_sites), per-URL status (inspect_url), sitemap listing (list_sitemaps), raw performance querying (search_performance), and period-over-period comparison (compare_periods). The only mild adjacency is search_performance vs compare_periods, but one is a granular grouped query and the other a fixed two-period diff with gain/loss highlights, so boundaries are clear.

Naming Consistency5/5

All five names follow a consistent snake_case verb_noun convention (inspect_url, list_sitemaps, list_sites, search_performance, compare_periods). Verbs are distinct and meaningfully matched to each action.

Tool Count5/5

Five tools is well-scoped for a focused Search Console surface, covering properties, sitemaps, URL inspection, analytics, and comparison without redundancy. Each tool earns its place.

Completeness4/5

Core read workflows (properties, sitemaps, URL inspection, search analytics, period comparison) are well covered. However, the surface is entirely read-only: there is no way to submit or delete a sitemap or request reindexing, which are natural Search Console operations and could cause dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues