MCP Server & REST API

Koala SEO provides both an MCP server for AI assistants and a REST API for direct integration.

MCP Server

The MCP server exposes tools for querying your Search Console data. Configure your AI assistant to connect:

https://koalaseo.net/api/mcp

Two ways to authenticate:

• OAuth - for ChatGPT, Claude.ai (web), or any client that supports connecting to a remote MCP server directly. Add the URL above as a custom connector and sign in when prompted; no key to copy. This is the only option for clients that connect straight to a URL rather than a local config file.
• API key - a Bearer token in the Authorization header, from Settings → API Keys. This is what local MCP clients (Claude Desktop, Cursor, Windsurf) use, since they read a config file rather than driving an OAuth popup.

Both are accepted on every request; the server tells them apart by the credential's shape, so nothing needs to be configured to pick one.

Available Tools

Composite analysis tools

The four composite tools chain several primitives into one pre-assembled evidence packet, so an AI assistant gets everything it needs for a workflow in a single call. All return deterministic numbers and comparisons - no generated text - so results are fast, cacheable, and reproducible.

Example: Claude Desktop

{
	"mcpServers": {
		"koala-seo": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote",
				"https://koalaseo.net/api/mcp",
				"--header",
				"Authorization: Bearer YOUR_API_KEY"
			]
		}
	}
}

For ChatGPT or Claude.ai (web), see Connect AI Assistants - those connect via OAuth instead of a config file.

REST API

All REST endpoints are under /api/v1 and require Bearer token authentication.

Sites

GET /api/v1/sites

Returns all connected sites with their basic stats.

Period Summary

GET /api/v1/properties/{siteUrl}/summary?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Returns clicks, impressions, CTR, and average position for the period.

Keywords

GET /api/v1/properties/{siteUrl}/keywords
GET /api/v1/properties/{siteUrl}/keywords/{keyword}

Trends

GET /api/v1/properties/{siteUrl}/trends/best?limit=10
GET /api/v1/properties/{siteUrl}/trends/worst?limit=10

Opportunities

GET /api/v1/properties/{siteUrl}/opportunities/quick-wins?limit=25
GET /api/v1/properties/{siteUrl}/opportunities/ctr?limit=25

Composite Analysis

GET /api/v1/properties/{siteUrl}/triage?days=28
GET /api/v1/properties/{siteUrl}/content-decay?days=90
GET /api/v1/properties/{siteUrl}/page-audit?url=https://example.com/page&strategy=mobile
GET /api/v1/properties/{siteUrl}/keywords/{keyword}/opportunity?days=28

Pre-assembled analysis packets mirroring the composite MCP tools: weekly triage, content decay candidates, per-page audit, and single-keyword opportunity report.

URL Inspection

GET /api/v1/properties/{siteUrl}/url-inspection?url=https://example.com/page

Returns Google's indexed-version status for a page, including coverage, last crawl, page fetch, robots, indexing, and canonical details.

PageSpeed

GET /api/v1/pagespeed?url=https://example.com/page&strategy=mobile

Returns PageSpeed Insights field and lab performance data. The dashboard uses mobile checks by default.

Search Performance

GET /api/v1/properties/{siteUrl}/keywords/{keyword}?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://koalaseo.net/api/v1/sites"

Response Format

All responses are JSON with the following structure:

{
  "data": { ... },
  "meta": {
    "siteUrl": "https://example.com",
    "startDate": "2025-01-01",
    "endDate": "2025-01-28"
  }
}

Error Responses

Rate Limits

The API has rate limits to ensure fair usage across all users. If you receive a 429 response, wait before retrying. Implement exponential backoff for repeated requests.