Skip to main content
Glama
Hexagon MCP

Hexagon MCP

by smallware-co
README.md
# Hexagon MCP

A read-only MCP server that lets an AI assistant like Claude read your own site data directly: Google Search Console, GA4, AdSense, Keyword Planner and Reddit. No exporting reports, no pasting screenshots into a chat. You ask a question, the assistant calls the right tool and answers from the rows it gets back.

Six sources, six tools, one server. Hence the name.

Built by [Smallware Co.](https://github.com/smallware-co). Landing page: [engineeredai.net/tools/hexagon-mcp](https://engineeredai.net/tools/hexagon-mcp/). Privacy policy: [engineeredai.net/tools/hexagon-mcp/privacy](https://engineeredai.net/tools/hexagon-mcp/privacy/).

## Status

Version 0.1.0. Search Console, GA4, AdSense and Keyword Planner are tested and working. The two Reddit tools are written but have not been tested against live credentials yet, so treat them as experimental. Transport is stdio, so any MCP client that can launch a local command can run it.

## Tools

| Tool | What it returns |
| --- | --- |
| `gsc_query` | Clicks, impressions, CTR and position from Search Console, by query, page, country, device or date. One property, or every property the account can access. |
| `ga4_report` | Any GA4 Data API dimensions and metrics. Defaults to top pages by views for the last 7 days. One property, or all of them grouped per property. |
| `adsense_report` | Estimated earnings, page views, impressions, clicks and CTR by day for the last 7 days by default, so highs and lows are visible without opening the dashboard. Other dimensions and date ranges are available. |
| `keyword_planner_ideas` | Average monthly searches, competition (LOW, MEDIUM or HIGH) and top of page bid range for seed keywords, by location, language, network and month range. |
| `reddit_trends` | Rising posts from the subreddits you name. A "what is picking up in my niche" signal that does not depend on Google Trends. |
| `reddit_demand` | Recommendation and buying intent threads in your niche, as a demand signal for product and affiliate content. |

Every tool is read-only. Nothing is created, changed or deleted on any platform.

## Example

Ask your assistant something like:

- "Which queries across my sites got impressions but almost no clicks in the last 30 days?"
- "Show my AdSense earnings by day for the last 7 days."
- "Give me Keyword Planner ideas for 'mcp server' in the US."

For the first question the assistant calls `gsc_query` once with every property included, and each property comes back with rows shaped like this (values are illustrative):

```json
{
  "siteUrl": "https://example.com/",
  "rows": [
    { "query": "example query", "clicks": 3, "impressions": 54, "ctr": 0.0556, "position": 5.8 }
  ]
}
```

## Who it is for

Solo operators and small content teams who want to understand what is working and what is worth writing about next, without a dedicated SEO hire or an agency retainer. It does not replace judgment or strategy. It removes the manual step of exporting a report or scanning several tabs before you can start asking questions.

## Bring your own credentials

Hexagon ships with no credentials and stores none. You authenticate with your own accounts, and everything runs on your own machine. There is no Hexagon server, no account and no telemetry.

Each tool only works if its credentials are in `.env`. A tool with missing credentials returns an error naming the missing variables, and the other tools keep working. You can set up Search Console and GA4 first and add the rest later.

You will need:

1. A Google Cloud project with the Search Console API, Analytics Data API and AdSense Management API enabled. Enable the Google Ads API too if you want Keyword Planner.
2. An OAuth client of type Desktop app from that project (client ID and secret).
3. For AdSense, your publisher ID in the format `pub-XXXXXXXXXXXXXXXX`.
4. Optionally, a default Search Console property URL exactly as it appears in Search Console (for example `sc-domain:example.com` or `https://example.com/`) and a default GA4 property ID. Leave them empty to query every property the Google account can access.
5. For Keyword Planner, a Google Ads developer token, Ads OAuth credentials, a customer ID, and Google Ads API access at the Basic level or higher. See the Keyword Planner section below.
6. For Reddit, a "script" type app created at [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps).

## Setup

```bash
git clone https://github.com/smallware-co/hexagon-mcp.git
cd hexagon-mcp
npm install
cp .env.example .env
```

Fill in `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `.env`, then get a refresh token:

```bash
npm run auth:google
```

Open the URL it prints, approve access, and the helper prints a `GOOGLE_REFRESH_TOKEN=...` line. Paste that line into `.env`. The helper requests read-only scopes for Search Console, Analytics and AdSense, and the token is only printed in your terminal.

Add your AdSense publisher ID, then add Hexagon to your MCP client config. Claude Desktop example:

```json
{
  "mcpServers": {
    "hexagon": {
      "command": "node",
      "args": ["/absolute/path/to/hexagon-mcp/src/index.js"]
    }
  }
}
```

On Windows, use a path like `C:\\Users\\you\\hexagon-mcp\\src\\index.js` with doubled backslashes. Restart your client and the tools will be available. The `.env` file is found relative to the server, so it does not matter which directory your client launches it from.

## Keyword Planner setup

Steps below were verified in October 2026. Google changes this process, so check each screen against what you see.

1. Fill in the `GOOGLE_ADS_` variables in `.env`: developer token, client ID, client secret and customer ID.
2. Run `npm run auth:google -- --ads` and paste the `GOOGLE_ADS_REFRESH_TOKEN=...` line into `.env`. This uses the `GOOGLE_ADS_` client pair and the Google Ads scope.
3. Check your Google Ads API access level in the Google Cloud Console under the Google Ads API page. New projects start at Test, then Explorer. Keyword Planner calls fail on Explorer with "This method is not allowed for use with explorer access". You need Basic.
4. To apply for Basic, your OAuth app needs brand verification. On the Branding page of your OAuth consent screen, fill in an app name, support email, home page, privacy policy, terms of service, an authorized domain and a logo that identifies your brand. A generic logo can be rejected with "Your logo does not uniquely identify your brand and identity". After verification passes, publish the branding.
5. Set `GOOGLE_ADS_CUSTOMER_ID` to an account you can reach. If a canceled ad account is refused as "not enabled or deactivated", use your manager account ID instead. `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is only needed when the customer is reached through a manager account.

Locations accept country codes (US, PH, GB, UK, CA, AU, IN, SG, NZ, IE, DE, FR) or any numeric geo target constant ID.

## Troubleshooting

- **"... is not configured. Missing in .env: ..."**: that tool's credentials are incomplete. The message names the variables.
- **"Google did not return a refresh token"**: remove the app's access at [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and run the helper again.
- **"User does not have sufficient permission for site"**: your `GSC_SITE_URL` does not match the property exactly as Search Console lists it. Leave it empty to query every property.

## What the Google scopes do

The helper requests read-only scopes for Search Console, Analytics and AdSense. For Keyword Planner, Google only offers a broader Google Ads scope, so Hexagon requests it, but only calls the keyword ideas service and does not create or change campaigns, keyword plans or settings. Details are in the [privacy policy](https://engineeredai.net/tools/hexagon-mcp/privacy/).

## Why not Google Trends?

Trends has no official API. The available workarounds scrape its internal endpoints, so they can break without warning. Reddit's rising endpoint is an official, stable API and surfaces posts that are gaining traction, which is closer to what Trends is meant to show than a plain top posts pull. It is a narrower signal, since Reddit attention is not the same as search demand, but it will not silently stop working.

## License

MIT

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation4/5

Each tool maps to a distinct data source (GSC, GA4, AdSense, Keyword Planner, Reddit), so selection is mostly unambiguous. The only mild overlap is reddit_trends vs reddit_demand, but their descriptions clearly separate 'rising posts' from 'buying-intent threads'.

Naming Consistency4/5

All names follow a consistent snake_case source_action pattern (gsc_query, ga4_report, adsense_report, reddit_trends, reddit_demand). Minor variation in the action suffix (query vs report vs ideas) is readable and intentional, not chaotic.

Tool Count5/5

Six tools is well-scoped for a read-only marketing-analytics aggregator, with each tool earning its place by covering a distinct data source. No redundant or filler tools.

Completeness4/5

The surface covers the core read-only research workflows across four Google data sources plus Reddit demand signals. Minor gaps exist (no property/account listing tool, no cross-source synthesis or trend comparison), but agents can work around these.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues