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

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

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.