CrawlForge MCP Server

serp_rank

Read-onlyIdempotent

Check where a domain ranks in Google organic search results for a keyword, returning its position, ranking URL, and all positions it holds. Requires DataForSEO credentials.

Instructions

Use this to check where a domain ranks in Google's ORGANIC results for a keyword - real SERP position, not Custom Search order. Returns the target's organic rank, the ranking URL, and every position it holds. Not for general search (search_web). One lookup is one sample: Google can return a different result set for the same query minutes apart (seResultsCount tells them apart), so compare several before reading a rank change. Requires DataForSEO credentials and returns configured:false without them - do not retry in that case. Cost: 5 credits (0 when unconfigured). Example: serp_rank({keyword: "managed wordpress hosting", target: "dashboardhosting.com", location_name: "United States"})

Input Schema

TableJSON Schema

Name	Required	Description
`depth`	No	How many results to scan, 10-200 (default 30; DataForSEO bills ~$0.002 per 10 and gets slower the deeper it goes)
`device`	No	Device to emulate
`target`	Yes	Domain or URL to locate in the results (e.g. 'example.com'). Matched by host, not exact URL: any page on that host or its subdomains counts
`keyword`	Yes	The search query to check ranking for
`language_code`	No	Language code (e.g. 'en')
`location_code`	No	Numeric DataForSEO location code (overrides location_name)
`location_name`	No	Location, e.g. 'United States' or 'London,England,United Kingdom'

Output Schema

TableJSON Schema

Name	Required	Description
`url`	No	URL of the target's best-ranking result
`cost`	No	USD charged by DataForSEO for this lookup (separate from CrawlForge credits)
`note`	No	Present when configured=false, explains how to enable
`_cost`	No	Cost-transparency metadata (D3.5), present when injected into the text copy of the result
`found`	No	Whether the target appeared anywhere in the scanned SERP
`title`	No
`device`	No
`target`	No	Host the SERP was matched against: a URL target is reduced to its host, and any page on it or its subdomains counts
`keyword`	No
`results`	No	Top organic competitors as Google actually ranks them (capped)
`checkUrl`	No	Link to view the real SERP on DataForSEO
`location`	No
`position`	No	Best (lowest) organic rank; null = not within top `depth`
`checkedAt`	No
`configured`	No	False when DATAFORSEO_LOGIN/PASSWORD are unset — no rank was fabricated
`allPositions`	No	Every position the target holds on this SERP
`depthScanned`	No
`rankAbsolute`	No
`organicResults`	No
`seResultsCount`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv6.19.2Oct 6, 2026

changedInput schema / properties / depth / description

Previous value: -"How many results to scan, 10-200 (default 20; DataForSEO bills ~$0.002 per 10 and gets slower the deeper it goes)"New value: +"How many results to scan, 10-200 (default 30; DataForSEO bills ~$0.002 per 10 and gets slower the deeper it goes)"

changedInput schema / properties / target / description

Previous value: -"Domain or URL to locate in the results (e.g. 'example.com')"New value: +"Domain or URL to locate in the results (e.g. 'example.com'). Matched by host, not exact URL: any page on that host or its subdomains counts"

changedOutput schema / properties / target / description

Previous value: -"Bare target domain, normalized"New value: +"Host the SERP was matched against: a URL target is reduced to its host, and any page on it or its subdomains counts"

Changed7 schema fields changedv6.0.0Sep 6, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
changedOutput schema / properties / _cost / additionalProperties
```
Previous value: -trueNew value: +{}
```
changedOutput schema / properties / allPositions / items / additionalProperties
```
Previous value: -trueNew value: +{}
```
removedOutput schema / properties / results / items / $ref
```
Removed value: -"#/properties/allPositions/items"
```
addedOutput schema / properties / results / items / additionalProperties
```
Added value: +{}
```

addedOutput schema / properties / results / items / properties

Added value: +{
+  "domain": {
+    "type": "string"
+  },
+  "position": {
+    "type": [
+      "number",
+      "null"
+    ]
+  },
+  "rankAbsolute": {
+    "type": [
+      "number",
+      "null"
+    ]
+  },
+  "snippet": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "title": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "url": {
+    "type": [
+      "string",
+      "null"
+    ]
+  }
+}

addedOutput schema / properties / results / items / type
```
Added value: +"object"
```

Changed1 schema field changedv5.0.5Aug 23, 2026

changedInput schema / properties / depth / description

Previous value: -"How many results to scan, 10-200 (100 = 1 page of cost)"New value: +"How many results to scan, 10-200 (default 20; DataForSEO bills ~$0.002 per 10 and gets slower the deeper it goes)"

Changed2 schema fields changedv5.0.4Aug 21, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "_cost": {
+      "additionalProperties": true,
+      "description": "Cost-transparency metadata (D3.5), present when injected into the text copy of the result",
+      "properties": {
+        "actual": {
+          "description": "Credits actually charged (0 in creator mode, half-rate on error)",
+          "type": "number"
+        },
+        "projected": {
+          "description": "Credits projected for this call before execution",
+          "type": "number"
+        },
+        "projection_note": {
+          "description": "Human-readable note about how the cost was projected",
+          "type": "string"
+        },
+        "remaining_credits": {
+          "description": "Credits remaining on the account after this call, if known",
+          "type": [
+            "number",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "allPositions": {
+      "description": "Every position the target holds on this SERP",
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "position": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "rankAbsolute": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "snippet": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "title": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "url": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "checkUrl": {
+      "description": "Link to view the real SERP on DataForSEO",
+      "type": "string"
+    },
+    "checkedAt": {
+      "type": "string"
+    },
+    "configured": {
+      "description": "False when DATAFORSEO_LOGIN/PASSWORD are unset — no rank was fabricated",
+      "type": "boolean"
+    },
+    "cost": {
+      "description": "USD charged by DataForSEO for this lookup (separate from CrawlForge credits)",
+      "type": "number"
+    },
+    "depthScanned": {
+      "type": "number"
+    },
+    "device": {
+      "type": "string"
+    },
+    "found": {
+      "description": "Whether the target appeared anywhere in the scanned SERP",
+      "type": "boolean"
+    },
+    "keyword": {
+      "type": "string"
+    },
+    "location": {},
+    "note": {
+      "description": "Present when configured=false, explains how to enable",
+      "type": "string"
+    },
+    "organicResults": {
+      "type": "number"
+    },
+    "position": {
+      "description": "Best (lowest) organic rank; null = not within top `depth`",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "rankAbsolute": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "results": {
+      "description": "Top organic competitors as Google actually ranks them (capped)",
+      "items": {
+        "$ref": "#/properties/allPositions/items"
+      },
+      "type": "array"
+    },
+    "seResultsCount": {
+      "type": "number"
+    },
+    "target": {
+      "description": "Bare target domain, normalized",
+      "type": "string"
+    },
+    "title": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "url": {
+      "description": "URL of the target's best-ranking result",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

First observedv4.10.0Jul 29, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, openWorld, idempotent, non-destructive), and the description adds rich context beyond them: the sampling variability of Google results, the seResultsCount field to distinguish samples, credential dependency, the configured:false outcome, and exact credit cost. This is unusually complete behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded with the core purpose and exclusion, followed by sampling, credential, and cost notes, ending with a concrete example. Every sentence earns its place and no redundant phrasing is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description needn't explain return values, and it covers the remaining gaps an agent needs: credential prerequisites, cost, sampling caveats, sibling exclusion, and a usage example. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters in detail. The description provides a concrete usage example but adds no parameter-specific meaning beyond what the schema already states (e.g., host matching, depth billing, location codes). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: check where a domain ranks in Google's organic results for a keyword, and explicitly distinguishes this from Custom Search order. It also names the sibling it is not (search_web), so an agent can route correctly without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when not to use it ('Not for general search (search_web)'), gives operational guidance about comparing multiple samples before reading a rank change, and states credential requirements plus the exact behavior when unconfigured (returns configured:false, do not retry). Alternatives and exclusions are unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.