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

Authentication is via Bearer token in the Authorization header.

Available Tools

Tool	Arguments	Description
`list_sites`	-	List all verified properties
`get_period_summary`	`siteUrl`, `startDate`, `endDate`	Get clicks, impressions, CTR, position
`get_top_keywords`	`siteUrl`, `limit?`	Get best performing keywords
`get_best_trends`	`siteUrl`, `limit?`	Keywords with biggest improvement
`get_worst_trends`	`siteUrl`, `limit?`	Keywords with biggest decline
`get_quick_wins`	`siteUrl`, `limit?`	Keywords ranking 11-20
`get_ctr_opportunities`	`siteUrl`, `limit?`	Low CTR in top positions
`inspect_url`	`siteUrl`, `url`, `languageCode?`	URL indexing and crawl status
`get_page_speed`	`url`, `strategy?`	PageSpeed performance metrics
`get_seo_triage_packet`	`siteUrl`, `days?`	One-call weekly triage: health, urgent issues, wins, ranked actions
`get_content_decay_candidates`	`siteUrl`, `days?`	Pages losing traffic plus the keywords bleeding clicks on each
`get_page_audit_packet`	`siteUrl`, `url`, `strategy?`	Per-page audit: indexing, crawl issues, PageSpeed, keyword coverage
`get_keyword_opportunity_report`	`siteUrl`, `keyword`, `days?`	Single-keyword deep dive: trend, CTR gap, upside, suggested action

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:

get_seo_triage_packet - "What do I fix this week?" Returns { healthSummary, urgentIssues, quickWins, ctrGaps, priorityActions }. Priority actions are ranked by estimated monthly click upside.
get_content_decay_candidates - Finds pages with >15% click decline vs the previous period and pinpoints which keywords drove the loss. Returns { decayedPages, losingPages }.
get_page_audit_packet - Combines URL Inspection, PageSpeed, and keyword coverage for one page, plus a 0-100 auditScore blending technical health (60%) and performance (40%).
get_keyword_opportunity_report - Daily trend, position delta, CTR vs position benchmark, expected monthly click upside, and a deterministic suggestedAction (recover-decline, improve-content-to-reach-page-1, rewrite-title-meta, or maintain).

All composite tools 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"
			]
		}
	}
}

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

Status	Meaning
`400`	Bad request - missing or invalid parameters
`401`	Unauthorized - invalid or missing API key
`403`	Forbidden - API key doesn't have access to this site
`404`	Not found - site or resource doesn't exist
`429`	Too many requests - rate limit exceeded
`500`	Server error - something went wrong on our end

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.