Grafana UI MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to Grafana UI components, documentation, stories, and design system tokens. This server enables AI tools like Claude Desktop, Continue.dev, and other MCP-compatible clients to retrieve and work with Grafana's React component library seamlessly.

🚀 Key Features

• Complete Component Access: Get the latest Grafana UI component TypeScript source code
• Rich Documentation: Access comprehensive MDX documentation with usage guidelines
• Interactive Stories: Retrieve Storybook stories with interactive examples and controls
• Test Files: Access test files showing real usage patterns and edge cases
• Design System Integration: Get Grafana's design tokens (colors, typography, spacing, shadows)
• Dependency Analysis: Understand component relationships and dependency trees
• Advanced Search: Search components by name and documentation content
• GitHub API Integration: Efficient caching and intelligent rate limit handling

🛠️ Unified Tool Interface

This MCP server provides a single unified tool called grafana_ui that consolidates all functionality through action-based routing. This reduces complexity and makes it easier for AI agents to understand and use.

🎯 The grafana_ui Tool

All operations are performed through one tool with an action parameter:

{
  "tool": "grafana_ui",
  "arguments": {
    "action": "get_component",
    "componentName": "Button"
  }
}

📋 Available Actions (11 Total)

Core Component Actions:

• get_component - Get TypeScript source code for any Grafana UI component
• get_demo - Get Storybook demo files showing component usage
• list_components - List all available Grafana UI components
• get_metadata - Get component props, exports, and metadata
• get_directory - Browse the Grafana UI repository structure

Advanced Grafana Actions:

• get_documentation - Get rich MDX documentation with sections and examples
• get_stories - Get parsed Storybook stories with interactive controls
• get_tests - Get test files showing usage patterns and edge cases
• search - Search components by name and optionally by documentation content
• get_theme_tokens - Get Grafana design system tokens (colors, typography, spacing, etc.)
• get_dependencies - Get component dependency tree analysis (shallow or deep)

✨ Benefits of the Unified Tool

• Simplified Integration: Only one tool to configure in MCP clients
• Easier for AI Agents: Reduced cognitive load with single entry point
• Better Context Management: All functionality accessible through one interface
• Parameter Validation: Comprehensive validation based on action type
• Future-Proof: Easy to add new actions without breaking changes

🔄 Migration from Previous Versions

Breaking Change: Version 2.0+ uses a unified tool interface. If you were using individual tools like get_component, list_components, etc., you now need to use the grafana_ui tool with an action parameter.

Before (v1.x):

{ "tool": "get_component", "arguments": { "componentName": "Button" } }

After (v2.0+):

{ "tool": "grafana_ui", "arguments": { "action": "get_component", "componentName": "Button" } }

All functionality remains the same - only the interface has changed.

📦 Quick Start

⚡ Using npx (Recommended)

The fastest way to get started - no installation required!

# Basic usage (rate limited to 60 requests/hour)
npx @shelldandy/grafana-ui-mcp-server

# With GitHub token for better rate limits (5000 requests/hour)
npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token_here

# Short form
npx @shelldandy/grafana-ui-mcp-server -g ghp_your_token_here

# Using environment variable (either option works)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
npx @shelldandy/grafana-ui-mcp-server

# Or using the common GITHUB_TOKEN variable
export GITHUB_TOKEN=ghp_your_token_here
npx @shelldandy/grafana-ui-mcp-server

🎯 Try it now: Run npx @shelldandy/grafana-ui-mcp-server --help to see all options!

🔧 Command Line Options

grafana-ui-mcp [options]

Options:
  --github-api-key, -g <token>     GitHub Personal Access Token
  --grafana-repo-path, -l <path>   Path to local Grafana repository (takes precedence)
  --help, -h                       Show help message
  --version, -v                    Show version information

Environment Variables:
  GITHUB_PERSONAL_ACCESS_TOKEN     Alternative way to provide GitHub token
  GITHUB_TOKEN                     Alternative way to provide GitHub token
  GRAFANA_REPO_PATH               Path to local Grafana repository

Examples:
  npx @shelldandy/grafana-ui-mcp-server --help
  npx @shelldandy/grafana-ui-mcp-server --version
  npx @shelldandy/grafana-ui-mcp-server -g ghp_1234567890abcdef
  npx @shelldandy/grafana-ui-mcp-server --grafana-repo-path /path/to/grafana
  npx @shelldandy/grafana-ui-mcp-server -l /path/to/grafana
  GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token npx @shelldandy/grafana-ui-mcp-server
  GITHUB_TOKEN=ghp_token npx @shelldandy/grafana-ui-mcp-server
  GRAFANA_REPO_PATH=/path/to/grafana npx @shelldandy/grafana-ui-mcp-server

🔑 GitHub API Token Setup

Why do you need a token?

• Without token: Limited to 60 API requests per hour
• With token: Up to 5,000 requests per hour
• Better reliability and faster responses
• Access to the complete Grafana UI component library

📝 Getting Your Token (2 minutes)

1. Go to GitHub Settings:

   • Visit GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)

2. Generate New Token:

   • Click "Generate new token (classic)"
   • Add a note: "Grafana UI MCP server"
   • Expiration: Choose your preference (90 days recommended)
   • Scopes: ✅ public_repo (for optimal access to Grafana repository)

3. Copy Your Token:

   • Copy the generated token (starts with ghp_)
   • ⚠️ Save it securely - you won't see it again!

🚀 Using Your Token

Method 1: Command Line (Quick testing)

npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token_here

Method 2: Environment Variable (Recommended)

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Then simply run:
npx @shelldandy/grafana-ui-mcp-server

Method 3: Claude Desktop Configuration

{
  "mcpServers": {
    "grafana-ui": {
      "command": "npx",
      "args": ["@shelldandy/grafana-ui-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

✅ Verify Your Setup

# Test without token (should show rate limit warning)
npx @shelldandy/grafana-ui-mcp-server --help

# Test with token (should show success message)
npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token --help

# Check your current rate limit
curl -H "Authorization: token ghp_your_token" https://api.github.com/rate_limit

🏠 Local Development Support

NEW: Work with a local Grafana repository for faster development and access to uncommitted changes!

🎯 Why Use Local Repository?

• ⚡ Faster Access: Direct filesystem reads, no network latency
• 🚫 No Rate Limits: Unlimited component access
• 🔄 Real-time Updates: See your local changes immediately
• 📡 Offline Support: Works without internet connection
• 🧪 Development Workflow: Test with modified/uncommitted components

🔧 Setup with Local Repository

1. Clone the Grafana Repository:

   git clone https://github.com/grafana/grafana.git
   cd grafana
   

2. Use Local Path (takes precedence over GitHub API):

   # Command line option
   npx @shelldandy/grafana-ui-mcp-server --grafana-repo-path /path/to/grafana
   npx @shelldandy/grafana-ui-mcp-server -l /path/to/grafana
   
   # Environment variable
   export GRAFANA_REPO_PATH=/path/to/grafana
   npx @shelldandy/grafana-ui-mcp-server
   

3. Claude Desktop Configuration:

   {
     "mcpServers": {
       "grafana-ui": {
         "command": "npx",
         "args": ["@shelldandy/grafana-ui-mcp-server"],
         "env": {
           "GRAFANA_REPO_PATH": "/path/to/your/grafana/repository"
         }
       }
     }
   }
   

🔄 Configuration Priority

The server checks sources in this order:

1. Local Repository (--grafana-repo-path or GRAFANA_REPO_PATH)
2. GitHub API with Token (--github-api-key or GITHUB_*_TOKEN)
3. GitHub API without Token (rate limited to 60 requests/hour)

🛡️ Graceful Fallback

• If local file doesn't exist → Falls back to GitHub API automatically
• If local repository is invalid → Falls back to GitHub API with warning
• Source is indicated in tool responses ("source": "local" vs "source": "github")

✅ Verify Local Setup

# Test local repository access
npx @shelldandy/grafana-ui-mcp-server --grafana-repo-path /path/to/grafana --help

# Should show: "Local Grafana repository configured: /path/to/grafana"

🛠️ Tool Usage Examples

The MCP server provides the unified grafana_ui tool for AI assistants:

Basic Component Access

// Get Button component source code
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_component",
    "componentName": "Button" 
  }
}

// List all available components
{
  "tool": "grafana_

---