Talk to Figma MCP

move_node

Reposition design elements in Figma by specifying new X and Y coordinates for precise layout adjustments.

Instructions

Move a node to a new position in Figma

Input Schema

TableJSON Schema

Name	Required	Description
`nodeId`	Yes	The ID of the node to move
`x`	Yes	New X position
`y`	Yes	New Y position

Implementation Reference

src/cursor_mcp_plugin/code.js:490-519 (handler)

Core implementation of move_node tool: retrieves Figma node by ID, validates parameters, updates node position (x, y), and returns updated node information.

async function moveNode(params) {
  const { nodeId, x, y } = params || {};

  if (!nodeId) {
    throw new Error("Missing nodeId parameter");
  }

  if (x === undefined || y === undefined) {
    throw new Error("Missing x or y parameters");
  }

  const node = await figma.getNodeByIdAsync(nodeId);
  if (!node) {
    throw new Error(`Node not found with ID: ${nodeId}`);
  }

  if (!("x" in node) || !("y" in node)) {
    throw new Error(`Node does not support position: ${nodeId}`);
  }

  node.x = x;
  node.y = y;

  return {
    id: node.id,
    name: node.name,
    x: node.x,
    y: node.y,
  };
}

src/talk_to_figma_mcp/server.ts:346-376 (registration)

MCP server.tool registration for 'move_node', including schema validation with Zod (nodeId, x, y) and handler that forwards to Figma plugin via sendCommandToFigma.

  "move_node",
  "Move a node to a new position in Figma",
  {
    nodeId: z.string().describe("The ID of the node to move"),
    x: z.number().describe("New X position"),
    y: z.number().describe("New Y position")
  },
  async ({ nodeId, x, y }) => {
    try {
      const result = await sendCommandToFigma('move_node', { nodeId, x, y });
      const typedResult = result as { name: string };
      return {
        content: [
          {
            type: "text",
            text: `Moved node "${typedResult.name}" to position (${x}, ${y})`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error moving node: ${error instanceof Error ? error.message : String(error)}`
          }
        ]
      };
    }
  }
);

src/talk_to_figma_mcp/server.ts:348-352 (schema)

Zod input schema for move_node tool parameters: nodeId (string), x (number), y (number).

{
  nodeId: z.string().describe("The ID of the node to move"),
  x: z.number().describe("New X position"),
  y: z.number().describe("New Y position")
},

src/cursor_mcp_plugin/code.js:83-84 (handler)
Dispatch handler case in Figma plugin code that routes 'move_node' command to the moveNode function.
```
case "move_node":
  return await moveNode(params);
```
src/talk_to_figma_mcp/server.ts:768-768 (helper)
Type union FigmaCommand includes 'move_node' for type safety in sendCommandToFigma calls.
```
| 'move_node'
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 15, 2025

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the move action and does not explain whether the move is absolute or relative, what coordinate system is used, whether the node must already exist, how the move interacts with parent/child relationships, or whether the operation is reversible.

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

Conciseness4/5

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

The description is a single, direct sentence with no filler or redundant detail, and the core action is front-loaded. It loses one point because the text is so minimal that it fails to include contextual guidance that would make the conciseness genuinely useful.

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?

The tool is simple and all three required parameters are fully documented in the schema, so the one-line description is minimally viable. However, with no annotations, no output schema, and sibling tools that overlap semantically, the description is not complete enough: it leaves the meaning of 'position' ambiguous and gives no usage or side-effect information.

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%, and the schema already defines nodeId, x, and y with clear descriptions. The tool description adds no additional parameter meaning, but it does not need to compensate because the schema already provides the essential semantics. Baseline 3 is appropriate.

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

Purpose4/5

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

The description uses a specific verb and resource — 'Move a node to a new position in Figma' — and the x/y parameters make it clear this is a coordinate move. It is not fully a 5 because 'new position' could be confused with moving a node in the hierarchy, especially given the sibling tool set_parent.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives such as set_parent, resize_node, or clone_node. The description does not mention exclusions, prerequisites, or any decision context, so the agent gets no help selecting between overlapping siblings.

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