QGIS MCP Server

Add Layout Map

add_layout_map

Add a map item to a QGIS print layout at a specified position and size in millimeters, with optional extent and scale to control the mapped area.

Instructions

Add a map item to a print layout at specified position and size (in millimeters). Optional extent=[xmin, ymin, xmax, ymax] and scale override the canvas view.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "layout_name": "<layout_name>",
      "x": "<x>",
      "y": "<y>",
      "width": "<width>",
      "height": "<height>"
    },
    "name": "add_layout_map"
  }
}

Input Schema

Name	Required	Description	Default
`x`	Yes
`y`	Yes
`scale`	No
`width`	Yes
`extent`	No
`height`	Yes
`layout_name`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 13, 2026

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are supplied, so the description carries the full burden. It does add useful behavior by specifying millimeter units and that extent/scale override the canvas view, but it omits what happens when both extent and scale are given, whether the call fails on a missing layout, and what is returned.

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?

Two sentences, front-loaded with the primary action and geometry units, followed by the optional override behavior. Nothing is redundant or padded.

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

Completeness3/5

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the geometry and override parameters but leaves gaps on preconditions, extent/scale conflict resolution, and error behavior. It is workable but not complete for a write operation.

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

Parameters4/5

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

With 0% schema coverage, the description compensates well: it gives units (mm) for position/size, the array format [xmin, ymin, xmax, ymax] for extent, and the override semantics of scale. It stops short of explaining scale's reference (map scale denominator) or precedence between extent and scale.

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 ('Add') and resource ('a map item to a print layout') plus the scope of position and size. An agent can distinguish it from siblings such as add_layout_label, add_layout_legend, or add_layout_picture purely from the noun 'map item'.

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

Usage Guidelines3/5

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

Usage is only implied: the required layout_name signals a layout must already exist, and the optional extent/scale are framed as overrides. There is no explicit statement of when to prefer extent versus scale, and no mention of alternatives for placing map frames.

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

Deploy Server