perch-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perch-mcp Make me a Perch widget that shows my Steam friends online"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
perch-mcp
The MCP server for building Perch mods. Point the AI tool you already use at it and it gets what only Perch can give it: the display vocabulary, the docs, the builtin packages as worked examples, a package validator, and a way to run your package in Perch.
Nothing here calls an AI. Your own client (Claude Code, Claude Desktop, Cursor, …) does the thinking on your own account.
Install
Requires Node 18+.
Claude Code
claude mcp add perch -- npx -y github:hlpdev/perch-mcpClaude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"perch": { "command": "npx", "args": ["-y", "github:hlpdev/perch-mcp"] }
}
}Cursor — .cursor/mcp.json (project) or the global one:
{
"mcpServers": {
"perch": { "command": "npx", "args": ["-y", "github:hlpdev/perch-mcp"] }
}
}Any other MCP client: run npx -y github:hlpdev/perch-mcp over stdio.
Related MCP server: Hanzo MCP
Tools
Tool | What it gives the model |
| The short authoring guide: package shape, Lua declarations, handlers, scopes, style. |
| The canonical vocabulary (api-spec.json): components and props, color roles, host functions, handlers, scopes, contexts. |
| The modding and API docs: list, read a page, or search. |
| The builtin packages (media, clock, weather, launcher, …) as complete examples. |
| Checks a package folder: manifest schema, entry, Lua syntax, widget declaration, component names. |
| Launches Perch with |
Try: "Make me a Perch widget that shows my Steam friends online, using the perch tools."
Updating the bundled content
content/ is generated from the Perch repos and committed:
npm run sync # needs ../perch, ../perch-studio, ../perch-site checked outAvailable Tools
6 toolsperch_docsPerch docsA
The modding and API documentation. Without page, lists pages (id, title, description); with page (e.g. "modding/your-first-widget", "api/host"), returns that page. search finds pages whose text mentions a term.
Inputs: page, search.
perch_examplesPerch builtin packagesA
The builtin Perch packages (media, clock, weather, launcher, …) are complete worked examples of the vocabulary. Without id, lists them; with id, returns every file of that package.
Inputs: id.
perch_guidePerch modding guideA
The short authoring guide for Perch mods: package shape, the Lua declarations (settings/widgets), handlers, scopes, style. Read this first.
Inputs: no named parameters.
perch_runRun a package in PerchA
Launches Perch with PERCH_MOD_DEV pointed at the folder that contains this package, so the widget appears in Settings → Layout → Widgets and on the notch. Windows only. Set PERCH_EXE if Perch is not installed through Steam.
Inputs: package_dir (required).
perch_validateValidate a Perch packageA
Checks a package folder: mod.json against the manifest schema (id = folder name, no legacy widgets/settings keys, known scopes), the entry exists, every .lua parses, the entry declares a widget, and display types exist in the vocabulary. The definitive check is Perch's own loader — run the package (perch_run) and read Settings → Installed mods for the loader's verdict.
Inputs: package_dir (required).
perch_vocabularyPerch display vocabularyA
The canonical vocabulary (api-spec.json): display components and their props, shared props, color roles, host functions, handlers, scopes, contexts. Pass part to fetch one section.
Inputs: part.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool addresses a distinctly different aspect of mod development: learning (guide), reference (vocabulary), documentation (docs), examples (examples), verification (validate), and execution (run). No two tools have overlapping purposes, eliminating ambiguity.
All tools follow the same lower_snake_case pattern with the 'perch_' prefix, and the second part is a clear noun or verb. The style is uniform, making the toolset predictable and easy to navigate.
With six tools, the set is compact and every tool has a clear role in the development workflow. This is within the ideal range and each tool earns its place without redundancy.
The tools cover the complete mod authoring loop: guidance, API reference, documentation, examples, validation, and runtime testing. No critical gaps are apparent for the stated purpose of developing Perch mods.
Related MCP Connectors
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Build and publish pages, manage collections, records and files in a Markerloop workspace.
Find Power Apps PCF controls, read their docs, and validate pcfhub.json manifests.
Build, test, publish and manage real MCP servers from APIs with a live developer studio.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides comprehensive access to MCP documentation through structured guides, full-text search, and interactive development workflows for building servers and clients.347 npmMIT
- AlicenseCqualityDmaintenanceEnables access to Hanzo APIs and Platform capabilities via MCP, along with development tools for managing and improving projects.71MIT
- AlicenseAqualityBmaintenanceAn MCP server that scaffolds runnable Roku channels from a validated AppSpec, zips them, and optionally sideloads to a Roku device.511 npmMIT
- AlicenseNot gradedqualityDmaintenanceSwiss-Army developer toolkit, stdio inspector, scaffolding CLI & built-in suite of developer tools for Model Context Protocol (MCP) servers.1MIT