Angular Storybook MCP Server

An MCP (Model Context Protocol) server that brings an Angular design system built on Storybook into Claude Code and Cursor, enabling AI-assisted development with real-time access to component metadata, APIs, and documentation.

This server only works against a design system whose Storybook build emits the manifests/components.json and manifests/docs.json files described below — it is not a generic Angular DS integration.

Overview

This MCP server exposes an Angular Storybook design system as a set of tools available to Claude. It fetches component metadata from a live Storybook instance and provides tools for:

• Listing all components — get a complete inventory of the design system
• Searching components — find components by name or keyword
• Component imports — get correct import paths for any component
• Component props — view all props, types, and defaults for a component
• Type details — inspect complex TypeScript types used by components
• Foundations — access design tokens (colors, typography, spacing, etc.)
• Peer dependencies — pointer to where required package versions can be found (not yet in the manifests)

Before you start: two things are required

This project has two independent halves, and both must be set up — one without the other doesn't work:

1. Install and configure this MCP server locally — see Setup below. This is the client-side piece that Claude Code or Cursor talks to.
2. Make your Storybook emit manifests/components.json and manifests/docs.json — see Bringing up a new design system repo. This is a one-time change to the Storybook project itself (Compodoc + the manifest addon), and it must re-run on every Storybook rebuild so the manifests stay current. Without it, there's nothing for this MCP server to fetch, no matter how correctly step 1 is configured.

Setup

Both Claude Code and Cursor talk to this MCP server using the same mcpServers config shape — only the config file location differs. Pick your editor below.

Setup for Cursor

Once the Storybook owner deploys with the manifests/components.json and manifests/docs.json files included, configure Cursor to use the live URL.

Edit .cursor/mcp.json (project-level, in your repo root) or ~/.cursor/mcp.json (global, applies to all projects):

{
  "mcpServers": {
    "angular-ds": {
      "command": "node",
      "args": ["<path-to-angular-ds-mcp-server>/dist/server.js"],
      "env": {
        "STORYBOOK_URL": "https://your-storybook-host.example.com"
      }
    }
  }
}

Then reload Cursor (Command Palette → "Reload Window", or fully restart Cursor). Open Cursor Settings → MCP to confirm the angular-ds server shows as connected.

Setup for Claude Code

Once the Storybook owner deploys with the manifests/components.json and manifests/docs.json files included, configure Claude Code to use the live URL.

Edit ~/.claude/claude.json:

{
  "mcpServers": {
    "angular-ds": {
      "command": "node",
      "args": ["<path-to-angular-ds-mcp-server>/dist/server.js"],
      "env": {
        "STORYBOOK_URL": "https://your-storybook-host.example.com"
      }
    }
  }
}

Then restart Claude Code. The tools will be available in all sessions.

Testing

After configuring Claude Code or Cursor, start a new chat and ask:

List all components in the design system

The assistant should call list_components and return the full component list. If it works, the MCP server is properly configured.

Building

npm install
npm run build

The built server will be at dist/server.js.

Development

Run the server in dev mode (with hot reload via tsx):

npm run dev

Or start the built server directly:

npm start

Architecture

• src/server.ts — Main MCP server entry point; registers all tools
• src/fetcher.ts — Handles fetching and caching manifests/components.json and manifests/docs.json from Storybook
• src/tools/ — Individual tool implementations:
  • list-components.ts — List all components
  • search-components.ts — Search by name/keyword
  • get-import.ts — Get import path
  • get-component-props.ts — Get component props
  • get-type-details.ts — Inspect TypeScript types
  • get-foundations.ts — Get design tokens
  • get-peer-dependencies.ts — Get version requirements

Environment Variables

• STORYBOOK_URL — Base URL where the manifest files are served. Required; the server throws on startup if it is not set.

Troubleshooting

"Failed to fetch component metadata"

• Check that STORYBOOK_URL points to a valid URL
• Verify manifests/components.json and manifests/docs.json exist at {STORYBOOK_URL}/manifests/components.json and {STORYBOOK_URL}/manifests/docs.json
• For local testing, ensure the http-server is running on the correct port

Tools not appearing in Claude Code / Cursor

• Verify ~/.claude/claude.json (Claude Code) or .cursor/mcp.json / ~/.cursor/mcp.json (Cursor) is properly formatted JSON
• Check that the dist/server.js file exists and is executable
• Restart Claude Code, or reload/restart Cursor, after updating the config

Slow first query

• The server caches metadata on startup. First query may take a few seconds while it fetches from Storybook.

Integration with your Design System

This server depends on your Angular Design System's Storybook build including two manifest files, manifests/components.json and manifests/docs.json. These are automatically generated as part of the Storybook build process and contain:

• manifests/components.json — component names, selectors, import statements, story snippets, and prop definitions (types, required flags, defaults, descriptions)
• manifests/docs.json — design tokens and other foundations documentation

Peer dependency information is not currently part of the manifests; the get_peer_dependencies tool points users to your design system package's own peerDependencies instead.

Bringing up a new design system repo (for Storybook owners)

None of this happens with a vanilla Storybook install — it requires two things wired into the target Angular repo:

1. Generate Angular metadata with Compodoc

Compodoc is a separate tool, not part of Storybook. Install it and add a script that runs it before Storybook starts/builds:

// package.json
"scripts": {
  "compodoc:lib": "compodoc -p <path-to-your-lib-tsconfig> -e json -d <output-dir> --silent",
  "prestorybook": "npm run compodoc:lib",
  "prebuild-storybook": "npm run compodoc:lib"
}

This produces a documentation.json file describing every component's inputs, outputs, and types.

2. Add the manifest addon + feature flag to .storybook/main.ts

addons: [
  'storybook-addon-angular-manifest', // must come BEFORE addon-docs
  '@storybook/addon-docs',
  // ...your other addons
  '@storybook/addon-mcp',
],
features: {
  componentsManifest: true, // Storybook 10.3+; use `experimentalComponentsManifest` on 10.2.x
},

Every story's meta must set component: (e.g. component: ButtonComponent) — without it, the addon can't resolve the Angular component name and the manifest entry comes out as an error.

3. Build and deploy Storybook as usual

npm run build-storybook now emits manifests/components.json and manifests/docs.json as static files alongside the rest of the Storybook site. Deploy that output wherever your Storybook is normally hosted (S3+CloudFront, a container behind nginx, etc.) — no special MCP-aware hosting is required, it's just two extra static JSON files.

4. Point this MCP server at it

Once the manifests are reachable at {your-storybook-url}/manifests/components.json and {your-storybook-url}/manifests/docs.json, set STORYBOOK_URL to that base URL (see Setup and Environment Variables above) — no changes to this server's code are needed.

Consumers on your team then just add this server to their own .cursor/mcp.json or ~/.claude/claude.json as shown in Setup, pointing STORYBOOK_URL at your deployed Storybook. Each person still builds/runs their own local copy of this server (it's a stdio server, not a hosted one) — only the Storybook + manifests need central deployment.