Start with one page.
Run these commands inside the project where you want to use GWG SEO. Replace the example URL with your website.
npm install @getwickedgrowth/seo@0.1.0
npx --no-install gwg-seo audit https://www.example.com/
The command prints a JSON report with coverage, data, and findings. A canonical pointing elsewhere or a noindex directive is an observation to review. Either can be intentional.
For a global command, use npm install --global @getwickedgrowth/seo@0.1.0. The package installs gwg-seo and seo. If either name already belongs to another tool, keep the project-local installation above and use npx --no-install gwg-seo.
Crawl, save, and share a report.
A crawl follows links on the same origin and respects robots rules. Start with a small page limit, inspect the failures and coverage, then expand the run if needed.
npx --no-install gwg-seo crawl https://www.example.com/ --max-pages 20 --max-depth 3 --save
npx --no-install gwg-seo audit https://www.example.com/ --format html --output ./audit.html
--save keeps a local snapshot. Use snapshots list and snapshots diff <before-id> <after-id> to compare observations. A finding disappearing from a smaller crawl does not prove it was fixed.
HTML output escapes report content and blocks scripts and external resources. The output file must be new; existing files are preserved.
Give your agent the same reports.
Use a client that supports local stdio MCP servers. After installing the package, generate the configuration for your installed copy:
npx --no-install gwg-seo mcp config
Copy the printed server entry into your client's MCP settings. It contains the Node executable and package path on your machine. The server starts with gwg-seo mcp serve; it does not require a hosted server URL. Regenerate the entry if you move the installation.
seo_reportslists implemented reports.seo_describereturns a report's input schema.seo_runruns the report and returns its evidence.
Try asking your agent: “Audit my homepage with GWG SEO. Show the observed URL for each finding and preserve the report's coverage limits.”
Install the optional agent skill
Replace the path below with your agent's skills directory. The installer creates a new gwg-seo directory and refuses to replace an existing one.
npx --no-install gwg-seo skill install --to /absolute/path/to/agent/skills
Call it from a Node.js application.
The CLI, library, and MCP server share a report engine. TypeScript declarations ship with the package.
import { auditPage } from '@getwickedgrowth/seo'
const result = await auditPage({
url: 'https://www.example.com/',
})
console.log(result.coverage, result.findings)
Run this in Node.js. The package is intended for local tools and server-side applications, and does not ship a browser bundle.
Eight reports in 0.1.0.
Use gwg-seo reports describe <id> to inspect the inputs before running a report.
| Report | What you receive |
|---|---|
page.auditWebsite | Inspect HTTP status, titles, descriptions, H1 headings, canonical links, indexing directives, image alt attributes, and JSON-LD syntax. |
site.crawlWebsite | Follow same-origin HTML links within page and depth limits. Review duplicate titles, per-page findings, and failed requests. |
site.robotsWebsite | Evaluate a URL against robots.txt for the GWG-SEO user agent and list declared sitemaps. |
site.sitemapWebsite | Read one XML sitemap or sitemap index, with a limit on the retained entries. |
google.sitesGoogle preview | List the Search Console properties accessible to your configured Google identity. |
google.searchGoogle preview | Read Search Console rows for explicit dates, dimensions, and a row limit. |
google.analyticsGoogle preview | Read GA4 organic-search landing pages with sessions, engaged sessions, and key events. |
search.opportunitiesGoogle preview | Prioritize Search Console rows with average positions 4-20 and a minimum impression threshold. |
Connect search data when you need it.
Google reports are a preview in 0.1.0. Automated fixtures cover API requests and response handling. Live Google-account validation is still outstanding, so verify the integration against your own properties before relying on it.
Bring a Google Desktop OAuth client or a service-account file with access to your Search Console and GA4 properties. There is no shared credential. Browser authorization uses gwg-seo auth login --client /path/to/desktop-client.json.
Search Console omits some query data. Analytics sessions and Search Console clicks measure different events. The opportunity report uses a position and impression threshold to prioritize review; it does not forecast traffic.
Follow the Google setup guide for API enablement, credentials, date ranges, and access requirements. You can also import a Search Console CSV with explicit property and date information.
Know what the report covers.
- Fetched HTML: audits do not execute JavaScript. A rendered page can contain additional content.
- Bounded acquisition: crawls default to 20 attempted pages and depth 3. Reports identify skipped URLs, truncated evidence, and request failures.
- Private networks: local and private addresses are blocked unless you explicitly enable them. Report parameters cannot turn on that access in an MCP server.
- Local storage: settings and saved reports stay in
~/.gwg-seo, or the directory selected withGWG_SEO_HOME. There is no telemetry or automatic report upload. - Your agent's handling: an MCP client can send report content to its model provider. Review URLs and analytics data before sharing reports.
Read the privacy notes and full acquisition limits. The issue tracker is the place to report a reproducible problem.
