Skip to main content
Glama
Sign In
LeoGCode

figma-reader-mcp

by LeoGCode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

figma_search

Read-only

Search Figma files for nodes by layer name or text content, supporting literal, regex, and instance override matching.

Instructions

Find nodes by name (and optionally text content). The query is a literal substring, case-insensitive unless case_sensitive: a name like Icons/Arrow/Left or /Card [v2]/ matches itself. Only regex=true reads it as a pattern, bare or /pattern/flags, and an invalid pattern is an error. With include_text, component instances are expanded, so strings that only exist as instance overrides or component property values are matched too, each tagged with via (direct/instance) and, where they apply, component, variant and frame. Name matching sees only real layers: layer names inside a collapsed instance live in its main component, so search that component instead. A hit's characters is a preview: longer text is cut to its first 120 characters followed by ... and flagged charactersTruncated (truncated, next to it, is about the number of results); figma_get_text returns the strings whole. When the text pass runs, unresolvedInstances counts the instances whose text could not be resolved and so was not searched (figma_get_text names the components); it is absent when the pass did not run. Pages in exclude_pages, or by default in the project's excludePages, are skipped before the limit is counted; excludedPages names the ones this search left out. Dated by exportedAt and account, or fileModifiedAt for a file read from disk, as the server's instructions say (figma-reader help on the command line).

Input Schema

NameRequiredDescriptionDefault
fileYesA local .fig path, a Figma file key or a figma.com/design/... URL (see the server's instructions, or figma-reader help)
pageNoRestrict to page name
limitNoDefault 50
queryYesName or text to find. A literal substring unless regex is set, so slashes and characters like [ ] ( ) . * match themselves
regexNoRead the query as a regex, bare or /pattern/flags, and report an invalid one. Default false: the query is a literal substring however it is written
typesNoNode types to match, e.g. FRAME, COMPONENT, INSTANCE, TEXT. A list without TEXT also turns include_text off, since every text hit is a TEXT node; an empty list is no filter at all
node_idNoSearch only this node and everything under it, like 12:34 (or 12-34); a node-id in the file URL is used when it is omitted, and the document's own id (0:0) is the whole file
refreshNoExport the live file again rather than read a local or cached copy (see the server's instructions, or figma-reader help)
include_textNoAlso match text content, including text rendered inside instances
exclude_pagesNoPages to skip, by name as page takes it. They are left out while walking, so their hits neither fill the limit nor count in total. Default: excludePages in the project's .figma-reader.json, unless page or a node_id other than the document's own (0:0) is given; an empty list searches every page
case_sensitiveNoMatch case (default false, for a regex too)
include_hiddenNoInclude text on layers hidden in the design (default false)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.4.2
    • addedInput schema / properties / exclude_pages
      Added value: +{
+  "description": "Pages to skip, by name as page takes it. They are left out while walking, so their hits neither fill the limit nor count in total. Default: excludePages in the project's .figma-reader.json, unless page or a node_id other than the document's own (0:0) is given; an empty list searches every page",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / file / description
      Previous value: -"Path to a local .fig file, or a Figma file key / figma.com/design/... URL. A node-id in the URL is used when this tool takes node_id and it is omitted; a tool that answers about the whole file ignores it. A key or URL uses a local '<name> [<key>].fig' from FIGMA_FILES_DIRS when one exists, otherwise exports through the browser."New value: +"A local .fig path, a Figma file key or a figma.com/design/... URL (see the server's instructions, or figma-reader help)"
    • changedInput schema / properties / node_id / description
      Previous value: -"Search only this node and everything under it, like 12:34 (or 12-34); a node-id in the file URL is used when it is omitted"New value: +"Search only this node and everything under it, like 12:34 (or 12-34); a node-id in the file URL is used when it is omitted, and the document's own id (0:0) is the whole file"
    • changedInput schema / properties / refresh / description
      Previous value: -"Skip local/cached copies and export the live file through the browser. Has no effect when file is a path to a .fig: that file is read as it is on disk and the result carries refreshIgnored; pass the key or URL to export the live file instead."New value: +"Export the live file again rather than read a local or cached copy (see the server's instructions, or figma-reader help)"
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already settle the safety profile (readOnlyHint=true, openWorldHint=true), and the description goes well beyond them: truncation at 120 characters with charactersTruncated, unresolvedInstances for text that could not be resolved, via/component/variant/frame tagging, and the ordering rule that excluded pages are skipped before the limit is counted. It stops short of stating auth requirements, rate limits, or per-call cost, so it is strong but not exhaustive.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is one undivided block of run-on sentences covering matching, instance expansion, truncation, exclusion, and timestamps. Every clause is arguably informative, yet nested asides such as '(truncated, next to it, is about the number of results)' make it hard to scan; splitting into matching/behaviour/return sections would preserve the content at lower reading cost.

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?

With 12 parameters, no output schema, and a subtle matching model, this description supplies exactly the missing context: what the returned fields mean (via, characters, charactersTruncated, unresolvedInstances, excludedPages) and where output is elided. An agent has enough to call the tool and interpret the result without further documentation.

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?

Schema description coverage is 100%, so the baseline is 3, but the description earns an increment by giving concrete, illustrative query forms ('Icons/Arrow/Left or /Card [v2]/ matches itself') and by clarifying cross-parameter interactions such as an invalid regex being an error and regex quoting behavior. Much of the remaining parameter detail duplicates the schema, which caps it below 5.

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?

The opening clause gives a specific verb and resource ('Find nodes by name (and optionally text content)') and immediately scopes the matching semantics. It also distinguishes itself from the sibling figma_get_text by stating that search returns a truncated preview while 'figma_get_text returns the strings whole', so an agent can route between the two without opening a schema.

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

Usage Guidelines4/5

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

Usage context is clearly established: when to set include_text, when the text pass does not run, and the important workaround that 'layer names inside a collapsed instance live in its main component, so search that component instead'. What is missing is an explicit statement of when NOT to use this tool versus figma_locate, figma_get_tree, or figma_get_text beyond the single truncation contrast.

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

Deploy Server

Other Tools