Atlassian Design System MCP Server

Current state: Early Access

The official Model Context Protocol (MCP) server for the Atlassian Design System. This server provides tools to access design tokens, icons, and components/primitives programmatically.

New: Remote MCP Server A hosted version of the ADS MCP server is now available at https://mcp.atlassian.com/v1/ads/public/mcp. Simply point your MCP client to this URL to get started. See the Usage section for per-IDE configuration examples.

Or, just click one of the buttons below to easily add the server to Cursor or VS Code.

New: Accessibility Analysis & Guidance The server now includes comprehensive accessibility tools to help ensure your interfaces are accessible to all users.

Table of Contents

• Available Tools
  • Design System Tools
  • Atlaskit Fallback Research Tools
  • Accessibility Tools
• Accessibility Features
  • Example Usage
• Usage
  • For AFM Users (internal Atlassians only)
  • For non-AFM Users
    • Cursor IDE
      • Local (stdio)
      • Remote
    • Visual Studio Code
      • Github Copilot
        • Local (stdio)
        • Remote
      • Codelassian
        • Local (stdio)
        • Remote
    • Rovodev
      • Local (stdio)
      • Remote
    • MCP Plugin for Atlas CLI
  • Environment Variables
• Analytics
  • What We Track
  • Privacy & Error Handling
• Development
• FAQs

Available Tools

Design System Tools

• ads_get_all_tokens - Get all available design tokens for colors, spacing, typography, etc.
• ads_search_tokens - Search for specific design tokens by name, description, or example values
• ads_get_all_components - Get all canonical ADS components with basic information (full catalog)
• ads_search_components - Search canonical ADS components by name, description, category, or package name
• ads_get_all_icons - Get all available icons from the design system
• ads_search_icons - Search for specific icons by name, keywords, or categorization
• ads_plan - Search for multiple design system resources (tokens, icons, components) in a single efficient operation

Use ads_* tools first for standard UI work. They are the canonical source for ADS components, tokens, icons, foundations, accessibility, lint rules, i18n, and migrations.

Atlaskit Fallback Research Tools

• atlaskit_get_components - Get a compact inventory of public @atlaskit/* component packages outside the ADS catalog
• atlaskit_search_components - Search non-ADS public @atlaskit/* components with examples and props
• atlaskit_get_hooks - Get a compact inventory of public @atlaskit/* hooks outside the ADS catalog
• atlaskit_search_hooks - Search non-ADS public @atlaskit/* hooks with usage details
• atlaskit_get_utilities - Get a compact inventory of public @atlaskit/* utilities outside the ADS catalog
• atlaskit_search_utilities - Search non-ADS public @atlaskit/* utilities with usage details

Use atlaskit_* tools for fallback research when an ADS search has no useful match, or when you are looking for a public @atlaskit/* package that is not part of ADS. Do not treat Atlaskit results as equal-priority replacements for ADS components in standard UI decisions.

Design System Tools Usage

// Search for canonical ADS components (recommended approach)
const buttonComponents = await ads_search_components({
    terms: ['button', 'click'],
    limit: 3,
});

// Search for specific tokens
const colorTokens = await ads_search_tokens({
    terms: ['color.text', 'primary'],
    limit: 5,
});

// Search for icons
const addIcons = await ads_search_icons({
    terms: ['add', 'plus', 'create'],
    limit: 2,
});

// Search for multiple resources at once (most efficient for complex UI patterns)
const designResources = await ads_plan({
    tokens: ['color.text', 'space.100', 'radius.small'],
    icons: ['add', 'edit', 'delete'],
    components: ['Button', 'TextField', 'Modal'],
    atlaskitComponents: [],
    limit: 2,
});

// Search public @atlaskit/* packages only when ADS has no useful match
const atlaskitComponents = await atlaskit_search_components({
    terms: ['editor-core', 'onboarding'],
    limit: 2,
});

// Get all available items (fallback when search doesn't find what you need)
const allComponents = await ads_get_all_components();
const allTokens = await ads_get_all_tokens();
const allIcons = await ads_get_all_icons();

Accessibility Tools

• ads_analyze_a11y - Analyze React component code for accessibility violations using axe-core and provide ADS-specific suggestions
• ads_analyze_localhost_a11y - Analyze whole web pages or specific elements (localhost or deployed URLs) for accessibility violations
• ads_get_a11y_guidelines - Get specific accessibility guidelines and best practices for different topics
• ads_suggest_a11y_fixes - Get specific fix suggestions for accessibility violations with code examples

Accessibility Features

The ADS MCP server includes comprehensive accessibility analysis and guidance:

• Axe-Core Analysis: Industry-standard accessibility testing using axe-core
• JSX to HTML Conversion: Accurate analysis by converting React JSX to HTML
• ADS-Specific Fixes: Get suggestions that use Atlassian Design System components and patterns
• WCAG 2.1 AA Compliance: Test against WCAG 2.1 AA standards
• Guidelines: Access detailed accessibility guidelines for buttons, forms, images, colors, focus management, and more
• Best Practices: Learn ADS-specific accessibility best practices and patterns
• Fallback Analysis: Pattern-based analysis if axe-core analysis fails

Example Usage

// Analyze a component for accessibility issues using axe-core
const analysis = await ads_analyze_a11y({
    code: `<button onClick={handleClose}><CloseIcon /></button>`,
    componentName: 'CloseButton',
    includePatternAnalysis: true, // Also include pattern-based analysis
});

// Get specific accessibility guidelines
const guidelines = await ads_get_a11y_guidelines({
    topic: 'buttons',
});

// Get fix suggestions for a violation
const fixes = await ads_suggest_a11y_fixes({
    violation: 'Button missing accessible label',
    code: `<button onClick={handleClose}><CloseIcon /></button>`,
});

Usage

For AFM Users (internal Atlassians only)

If you are working in the AFM root folder or any of the main product folders (platform/, jira/, confluence/, post-office/, confluence/, or townsquare/), ads-mcp is pre-configured and ready to use with supported tools like Cursor, VSCode (Copilot/Codelassian), and Rovodev.

For most users, ads-mcp is pre-configured in AFM, but you may need to manually enable it in Cursor or Copilot. Rovodev users get ads-mcp enabled automatically anywhere within AFM. For other tools, make sure you are running them from the AFM root or one of the main product folders to access ads-mcp.

For non-AFM Users

Cursor IDE

Local (stdio)

Add the following entry to your mcp.json file (located at ~/.cursor/mcp.json for user-level or .cursor/mcp.json in your workspace):

{
    "mcpServers": {
        "ads-mcp": {
            "command": "npx",
            "args": ["-y", "@atlaskit/ads-mcp"],
            "env": {
                "ADSMCP_AGENT": "cursor"
            }
        }
    }
}

Remote

Click to add or add the following to the same mcp.json file:

{
    "mcpServers": {
        "ads-mcp": {
            "url": "https://mcp.atlassian.com/v1/ads/public/mcp"
        }
    }
}

Visual Studio Code

Github Copilot

Local (stdio)

Add the following entry to your mcp.json file (located at ~/Library/Application Support/Code/User/mcp.json for user-level or .vscode/mcp.json in your workspace):

{
    "servers": {
        "ads-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@atlaskit/ads-mcp"]
        },
        "env": {
            "ADSMCMP_AGENT": "vscode"
        }
    }
}

Remote

Click or add the following to the same mcp.json file:

{
    "servers": {
        "ads-mcp": {
            "type": "http",
            "url": "https://mcp.atlassian.com/v1/ads/public/mcp"
        }
    }
}

Codelassian

Local (stdio)

Add the following entry to your mcp.json file (located at ~/.codelassian/mcp.json for user-level or .codelassian/mcp.json in your workspace):

{
    "mcpServers": {
        "ads-mcp": {
            "command": "npx",
            "args": ["-y", "@atlaskit/ads-mcp"],
            "env": {
                "ADSMCP_AGENT": "codelassian"
            }
        }
    }
}

Remote

No local installation required. Add the following to the same mcp.json file:

{
    "mcpServers": {
        "ads-mcp": {
            "type": "streamableHttp",
            "url": "https://mcp.atlassian.com/v1/ads/public/mcp",
            "disabled": false
        }
    }
}

Rovodev

Local (stdio)

Add the following entry to your mcp.json file (located at ~/.rovodev/mcp.json for user-level or mcp.json in your workspace):

{
    "mcpServers": {
        "ads-mcp": {
            "command": "npx",
            "args": ["-y", "@atlaskit/ads-mcp"],
            "env": {
                "ADSMCP_AGENT": "rovodev"
            }
        }
    }
}

Note:
The timeout field is supported in the Rovodev configuration. For example, setting "timeout": 300 will specify the maximum time in seconds that the MCP server will wait before terminating the process if it becomes unresponsive. Adjust this value as needed for your environment or workflow.

Remote

No local installation required. Add the following to the same mcp.json file:

{
    "mcpServers": {
        "ads-mcp": {
            "url": "https://mcp.atlassian.com/v1/ads/public/mcp"
        }
    }
}

MCP Plugin for Atlas CLI

Atlas CLI provides a plugin for managing MCP servers, including listing available servers from a registry and installing new ones.

To install the MCP plugin, run:

atlas plugin install -n mcp

Once the plugin is installed, you can add the MCP server on Rovodev (at the user-level) with:

atlas mcp install --name=ads-mcp --agent=rovodev

Note:
To see the list of available agents, visit: Introducing the MCP plugin for Atlas CLI

Environment Variables

The ADS MCP server supports several environment variables, mainly for analytics purposes to help improve the service. These variables enable platform identification, specification of configuration paths, and opting out of analytics collection if needed.

Note: All environment variables are optional. The MCP server will work without any of them set.

• ADSMCP_AGENT - Identifies the AI agent/platform using the MCP server. Supported values:

  • cursor - Cursor editor
  • vscode - Visual Studio Code
  • rovodev - Rovo Development environment
  • codelassian - Codelassian platform
  • unknown - Default value when not specified

  The ADSMCP_AGENT variable helps track which platforms are using the MCP server for analytics purposes.

• ADSMCP_CONFIG_PATH - Specifies the path to the MCP config file being used to run the server. This is used for analytics to understand where the server is being configured from (e.g., mcp.json, jira/.cursor/mcp.json, platform/.vscode/mcp.json). Defaults to unknown if not specified.

• ADSMCP_ANALYTICS_OPT_OUT - Opt out of analytics collection. Set to true to disable:

{
    "mcpServers": {
        "ads": {
            "command": "npx",
            "args": ["-y", "@atlaskit/ads-mcp"],
            "env": {
                "ADSMCP_AGENT": "codelassian",
                "ADSMCP_CONFIG_PATH": "platform/.codelassian/mcp.json",
                "ADSMCP_ANALYTICS_OPT_OUT": true
            }
        }
    }
}

Analytics

The MCP server includes built-in analytics to help improve the service. Analytics are sent to Atlassian's internal analytics system and track:

What We Track

• Tool Usage: Which tools are being called (e.g., ads_plan, ads_analyze_a11y)
• Tool Parameters: Arguments passed to tools (search terms, component names, etc.)
• Success/Failure: Whether tool calls succeed or fail, including error messages
• Environment Context:
  • agent: The platform using the MCP server (from ADSMCP_AGENT env var)
  • os: Operating system name (darwin, win32, linux)
  • osVersion: Operating system version (e.g., 24.6.0 for macOS)
  • version: The version of @atlaskit/ads-mcp being used
  • staffId: User identifier (from STAFF_ID, USER, ATLAS_USER, or username)
  • timestamp: When the event occurred

Privacy & Error Handling

• Analytics are collected for internal Atlassian use only to improve the MCP server
• You can opt out by setting ADSMCP_ANALYTICS_OPT_OUT=true in your environment variables
• If the analytics client fails to initialize or send events, the MCP server continues to work normally
• All analytics errors are caught and logged, ensuring they never interrupt your workflow
• Events are batched and flushed every 5 seconds for efficiency

Development

You may automatically be served the local version of @atlaskit/ads-mcp depending on where you're running it from, but you should force it like so:

{
    "mcpServers": {
        "ads": {
            "command": "npx",
            "args": [
                "-y",
                "~/git/atlassian/atlassian-frontend-monorepo/platform/packages/design-system/ads-mcp"
            ],
            "env": {
                "ADSMCP_AGENT": "cursor"
            }
        }
    }
}

Maintainer release workflow (AFM)

When ADS structured content changes:

1. From platform/, run combined codegen once:

afm workspace @af/ads-ai-tooling codegen

2. Commit updated generated MCP outputs in this package.
3. Add a platform/.changeset/*.md entry for @atlaskit/ads-mcp in the same PR. Use patch for catalog or documentation refreshes; use minor or major when the package API changes.
4. Create and ship the @atlaskit/ads-mcp release as usual.
5. Wait for the package publish.
6. Renovate should bump it in atlassian-mcp-micros.
7. Redeploy atlassian-mcp-micros after the bump lands (async pipeline).

For generated skills and DESIGN.md output, use the cross-repository sync workflow in packages/design-system/ai-tooling/README.md, then follow the destination README in atlassian/skills. The codegen runner does not create instruction files under platform/tmp/.

FAQs

1. I'm seeing an error like "Error: Cannot find module /Users/[username]/.npm/_npx/[hash]/node_modules/[module]/..."

   This usually means the cached package is corrupted or outdated. To resolve:

   1. Disable ads-mcp in your list of installed MCP servers.
   2. Delete the affected /Users/[username]/.npm/_npx/[hash] directory.
   3. Re-enable ads-mcp in your MCP servers.

2. In VSCode (Copilot), ads-mcp keeps auto-starting in the chat panel even when disabled.

   To prevent auto-start:

   1. Open VSCode settings.
   2. Search for @feature:chat mcp.
   3. Set Chat › Mcp: Autostart to never.

3. Who should I contact for support or questions?

   For internal Atlassians, please reach out in the #help-ads-ai Slack channel with any issues or inquiries.