modelbrain-search-console
Official# 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
Scored across 5 tools
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.
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.
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.
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.