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

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, 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 constraints.

Located in 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:

// 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, 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.

// 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.

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.

// 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, 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.

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 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. The crawler respects 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 and 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. Each keyword/device combination consumes credits during live checks, with costs calculated before execution to prevent unexpected quota exhaustion.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}