Polaris MCP Server

1.0.0 verified Sat Apr 25 auth: no javascript

A Model Context Protocol (MCP) server that provides tools and prompts for working with Shopify Polaris UI components. Version 1.0.0 enables AI assistants to search components, get detailed props and best practices, and retrieve code examples. It supports Node.js >=14.17.0 and is designed for Cursor or Claude Desktop integration. Key differentiators: specialized prompts for component implementation and layout design, and direct access to Polaris component data without manual documentation lookups.

Common errors

error Error: Cannot find module '@modelcontextprotocol/sdk' ↓

cause Missing dependency when running via npx without installing locally.

fix

Ensure npx fetches the package correctly; if using local install, run 'npm install @modelcontextprotocol/sdk'.

error Error: listen EADDRINUSE :::0 ↓

cause Another instance of the MCP server is already running using the same transport.

fix

Kill the previous process or use a different transport (e.g., change port if using SSE).

error Tool not found: search_polaris_components ↓

cause Client is connecting to a different MCP server or the server failed to register tools.

fix

Check server logs for startup errors. Ensure client configuration points to the correct server name.

Warnings

gotcha Windows users must use 'cmd /k npx -y polaris-mcp-server' instead of direct npx command. ↓

fix Use the alternative Windows config: { command: 'cmd', args: ['/k', 'npx', '-y', 'polaris-mcp-server'] }

deprecated The 'get_component_examples' tool may return stale examples if the data folder is not refreshed. ↓

fix Re-run 'npm run scrape' to update component data.

gotcha Component data is pre-scraped and bundled; it may not reflect the latest Polaris documentation. ↓

fix Re-generate the data by running the scraper script periodically.

Install

npm install polaris-mcp-server

yarn add polaris-mcp-server

pnpm add polaris-mcp-server

Imports

Server

import { Server } from '@modelcontextprotocol/sdk/server/index.js'

ESM-only. SDK version must be compatible with MCP protocol.

StdioServerTransport

wrong

import { StdioServerTransport } from '@modelcontextprotocol/sdk'

correct

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

Exported from subpath 'server/stdio.js', not root.

CallToolRequestSchema

import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

Type schema for tool requests.

Quickstart

Configures the MCP client to use polaris-mcp-server and demonstrates calling the three available tools: search, details, examples.

// Add to MCP client config (e.g., Cursor or Claude Desktop):
// {
//   "mcpServers": {
//     "polaris-mcp-server": {
//       "command": "npx",
//       "args": ["-y", "polaris-mcp-server@latest"]
//     }
//   }
// }

// Then use in your AI assistant:
// Search for components
const result = await use_mcp_tool('polaris-mcp-server', 'search_polaris_components', {
  query: 'button',
  category: 'Actions'
});

// Get details
const details = await use_mcp_tool('polaris-mcp-server', 'get_component_details', {
  componentName: 'Button'
});

// Get examples
const examples = await use_mcp_tool('polaris-mcp-server', 'get_component_examples', {
  componentName: 'Button'
});