# OpenSEO Reporting Capabilities: Complete Guide to MCP-Based SEO Analysis

> Explore OpenSEO reporting capabilities with six MCP-based tools for site audits, GA4 analytics, Search Console, backlinks, rank tracking, and local SEO. Get structured JSON and markdown.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: complete-guide
- Published: 2026-09-08

---

**OpenSEO provides six specialized MCP-based reporting tools—including site audits, GA4 analytics, Search Console insights, backlink profiles, rank tracking, and local SEO grids—that return structured JSON and pre-formatted markdown through a unified Zod-validated schema.**

OpenSEO (from the `every-app/open-seo` repository) is an open-source SEO platform built around a modular **Managed Cloud Platform (MCP)** architecture. Its **reporting capabilities** expose rich analytics through dedicated tool functions that deliver both machine-readable data arrays and human-friendly markdown tables, enabling seamless integration with automated SEO workflows and external dashboards.

## Core Reporting Architecture

OpenSEO implements all reports as **MCP tools** that share a common output contract. Every report generator returns data conforming to `reportOutputSchema`, enforced at runtime by **Zod** to guarantee predictable shapes even when external APIs change.

The standardized schema contains three critical fields:

- **`reportMetadata`** – Timestamps, data-quality flags, and provider-imposed limits
- **`rows`** – Core tabular data arrays for programmatic processing
- **`text`** – Auto-generated markdown tables ready for UI rendering

### Architectural Flow

When you request a report, OpenSEO processes the call through four distinct layers:

1. **Client Request** → An MCP tool function (e.g., `getAuditIssues`)
2. **Tool Handler** validates input using Zod schemas located in the tool definition files
3. **Service Layer** (`src/server/lib/...`) executes the heavy lifting—crawling sites, querying Google APIs, or fetching backlink data
4. **Result Envelope** packages the output using the shared schema and returns it to the caller

Production builds log usage telemetry via [`src/server/lib/self-host-telemetry.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/self-host-telemetry.ts), while self-hosted installations remain exempt from tracking.

## Site Audit Reports

The **site audit** system performs comprehensive technical SEO analysis by crawling entire domains while respecting [`robots.txt`](https://github.com/every-app/open-seo/blob/main/robots.txt) constraints.

Located in [`src/server/mcp/tools/site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/site-audit-tools.ts), this toolset audits every page for broken links, missing or duplicate titles, redirect chains, canonical conflicts, and thin content. It optionally runs **Lighthouse** performance checks on a representative sample of pages.

Because large-scale crawls execute as background jobs, the workflow requires asynchronous polling:

```typescript
// 1️⃣ Start a site audit (background job)
const auditId = await startSiteAudit({ url: "https://example.com" });

// 2️⃣ Poll until the audit finishes
let status;
do {
  status = await getAuditStatus({ auditId });
  await new Promise(r => setTimeout(r, 1_000));
} while (!status.finished);

// 3️⃣ Retrieve the prioritized issue report
const report = await getAuditIssues({ auditId });
console.log(report.text);      // Human‑readable markdown table
console.log(report.rows);      // Structured rows for UI rendering

```

The `getAuditIssues` function returns a prioritized issue list that remains **partial** if the crawl stopped early due to limits or interruptions, ensuring you receive actionable data even on incomplete runs.

## Google Analytics 4 (GA4) Reports

OpenSEO integrates directly with **Google Analytics 4** to provide traffic-acquisition and page-performance metrics without manual API configuration.

Implemented in [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts), the GA4 reporting suite supports filtered queries by channel (Organic Search, Paid, Direct, etc.) and automatically flags data limitations when Google marks reports as sampled or thresholded.

```typescript
// GA4 traffic‑acquisition report (JSON + markdown)
const ga4Report = await getGa4Report({
  propertyId: "123456789",
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  reportKind: "traffic_acquisition",
});
console.log(ga4Report.text);

```

Each response includes the standard metadata envelope indicating any data-quality warnings alongside the formatted metrics table.

## Google Search Console Reports

The **Search Console** integration delivers both aggregate analytics and individual URL inspection data through [`src/server/mcp/tools/search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/search-console-tools.ts).

### Search Analytics

Retrieve clicks, impressions, CTR, and average position metrics with flexible dimension filtering.

### URL Inspection

Check index coverage status, canonical declarations, mobile usability verdicts, and rich result eligibility for specific URLs. The tool returns inline failure messages for any URLs that cannot be processed.

```typescript
// Search Console URL inspection (partial failures inline)
const inspection = await inspectUrls({
  propertyId: "UA-987654321",
  urls: ["https://example.com/page1", "https://example.com/page2"],
});
console.log(inspection.text); // Shows per‑URL results and any errors

```

## Backlink Profile Reports

Located in [`src/server/mcp/tools/get-backlinks-profile.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/get-backlinks-profile.ts), the backlink profiler enumerates referring domains with authority scores and anchor-text distributions.

The `getBacklinksProfile` tool aggregates rows across multiple pages and explicitly reports any limits imposed by underlying data providers, ensuring transparency when datasets are truncated.

## Rank Tracking Reports

For live **SERP position monitoring**, OpenSEO offers real-time rank checking through [`src/server/mcp/tools/run-rank-tracker.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/run-rank-tracker.ts).

This system uses a credit-based consumption model. Before executing a run, call `estimateRankTrackerCost` to calculate the exact credit requirement for your keyword/device matrix. The `runRankTracker` function then executes live searches, returning current positions, historical trends, and quota-exceeded errors where applicable.

## Local SEO Grid Reports

The **Local SEO** tool in [`src/server/mcp/tools/local-seo-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/local-seo-tools.ts) executes a coordinate-based grid of Google Maps searches to visualize geographic ranking variations.

Specify a central coordinate, and the tool returns a matrix showing where your business ranks at each grid point, complete with result counts and top-ranked competitors for every location cell.

## Working with Report Outputs

Regardless of report type, all OpenSEO tools return outputs through the standardized `reportOutputSchema`. This consistency allows you to build generic UI components that consume `report.rows` for data visualization while displaying `report.text` for immediate human review.

The Zod validation ensures that fields like `reportMetadata.limits` and `reportMetadata.timestamp` are always present, enabling your applications to handle data freshness and truncation warnings programmatically.

## Summary

- **Six MCP-based tools** cover comprehensive SEO monitoring: site audits, GA4 analytics, Search Console data, backlink profiles, rank tracking, and local SEO grids
- **Unified Zod-validated schema** guarantees consistent `reportMetadata`, `rows`, and `text` fields across all report types
- **Asynchronous processing** handles large site audits via polling patterns using `startSiteAudit` and `getAuditStatus`
- **Credit-based pricing** applies to real-time rank tracking, with cost estimation available before execution
- **Self-hosted deployments** bypass telemetry logging entirely, keeping all reporting data private

## Frequently Asked Questions

### What data format do OpenSEO reports return?

All OpenSEO reporting tools return a structured JSON envelope following the `reportOutputSchema` defined in the tool handlers. Each response includes `reportMetadata` (timestamps and limits), `rows` (tabular data arrays), and `text` (pre-formatted markdown tables), ensuring both API consumers and human readers receive appropriately formatted information.

### How does the site audit report handle large websites?

The site audit runs asynchronously as a background job initiated by `startSiteAudit`. You must poll `getAuditStatus` until completion, then retrieve prioritized issues via `getAuditIssues` from [`src/server/mcp/tools/site-audit-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/site-audit-tools.ts). The crawler respects [`robots.txt`](https://github.com/every-app/open-seo/blob/main/robots.txt) and can return partial results if the crawl stops early due to limits or interruptions.

### Can OpenSEO reports integrate with existing analytics platforms?

Yes. The GA4 and Search Console tools in [`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts) and [`src/server/mcp/tools/search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/search-console-tools.ts) directly query Google's APIs, returning normalized data that can feed into custom dashboards. The standardized output schema ensures consistent data shapes across different report types.

### What is the cost model for rank tracking reports?

Rank tracking uses a credit-based system managed through `estimateRankTrackerCost` and `runRankTracker` in [`src/server/mcp/tools/run-rank-tracker.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/run-rank-tracker.ts). Each keyword/device combination consumes credits during live checks, with costs calculated before execution to prevent unexpected quota exhaustion.