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:

typescriptCopy code
{
  "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):

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

After (v2.0+):

typescriptCopy code
{ "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!

bashCopy code
# 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

bashCopy code
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)

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

Method 2: Environment Variable (Recommended)

bashCopy code
# 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

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

✅ Verify Your Setup

bashCopy code
# 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:

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

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

   bashCopy code
   # 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:

   jsonCopy code
   {
     "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

bashCopy code
# 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

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

// List all available components
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "list_components"
  }
}

// Get component metadata and props
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_metadata",
    "componentName": "Alert" 
  }
}

Advanced Documentation & Stories

typescriptCopy code
// Get rich MDX documentation for a component
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_documentation",
    "componentName": "Button" 
  }
}

// Get Storybook stories with interactive examples
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_stories",
    "componentName": "Input" 
  }
}

// Get test files showing usage patterns
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_tests",
    "componentName": "Modal" 
  }
}

Search & Discovery

typescriptCopy code
// Search components by name
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "search",
    "query": "button" 
  }
}

// Search components including documentation content
{
  "tool": "grafana_ui",
  "arguments": {
    "action": "search",
    "query": "form validation",
    "includeDescription": true
  }
}

Design System & Dependencies

typescriptCopy code
// Get all design system tokens
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_theme_tokens"
  }
}

// Get specific token category (colors, typography, spacing, etc.)
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_theme_tokens",
    "category": "colors" 
  }
}

// Get component dependencies (shallow)
{
  "tool": "grafana_ui",
  "arguments": { 
    "action": "get_dependencies",
    "componentName": "Button" 
  }
}

// Get deep dependency analysis
{
  "tool": "grafana_ui",
  "arguments": {
    "action": "get_dependencies",
    "componentName": "DataTable",
    "deep": true
  }
}

🔗 Claude Desktop Integration

Add to your Claude Desktop configuration (~/.config/Claude/claude_desktop_config.json):

jsonCopy code
{
  "mcpServers": {
    "grafana-ui": {
      "command": "npx",
      "args": [
        "@shelldandy/grafana-ui-mcp-server",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

Or with environment variable:

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

🔗 Cursor Integration

Add to your Cursor configuration file. Access this through:

• Windows/Linux: Ctrl+Shift+P → "View: MCP Settings" → New MCP Server
• macOS: Cmd+Shift+P → "View: MCP Settings" → New MCP Server

Method 1: With GitHub Token as Argument

jsonCopy code
{
  "mcp": {
    "grafana-ui": {
      "command": "npx",
      "args": [
        "@shelldandy/grafana-ui-mcp-server",
        "--github-api-key",
        "ghp_your_token_here"
      ]
    }
  }
}

Method 2: With Environment Variable (Recommended)

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

After adding the configuration, restart Cursor to enable the MCP server. You can then use the Grafana UI tools in your conversations with Cursor's AI assistant.

🏗️ Component Architecture

Grafana UI components follow a rich multi-file structure:

Copy code
packages/grafana-ui/src/components/ComponentName/
├── ComponentName.tsx          # Main component implementation
├── ComponentName.mdx          # Rich documentation with examples
├── ComponentName.story.tsx    # Storybook stories and interactive examples
├── ComponentName.test.tsx     # Test files showing usage patterns
├── types.ts                   # TypeScript type definitions
├── utils.ts                   # Utility functions
└── styles.ts                  # Styling utilities (if applicable)

This server provides access to all these files, giving AI assistants comprehensive understanding of each component.

🔍 What's Covered

The server provides access to 200+ Grafana UI components including:

• Input Components: Button, Input, Checkbox, Radio, Select, Switch, Slider
• Display Components: Alert, Badge, Tag, Tooltip, Card, Panel, Stat
• Layout Components: Layout, Container, Stack, Grid, Divider
• Navigation Components: Menu, Breadcrumb, Tabs, Steps, Pagination
• Data Components: Table, DataTable, List, Tree, Timeline
• Feedback Components: Modal, Drawer, Notification, Spinner, Progress
• Advanced Components: DatePicker, CodeEditor, Graph, Chart components

Plus access to:

• Design System Tokens: Complete color palettes, typography scales, spacing system
• Theme Files: Light/dark mode configurations
• Utility Functions: Helper functions and shared utilities

🐛 Troubleshooting

Common Issues

"Rate limit exceeded" errors:

bashCopy code
# Solution: Add GitHub API token
npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token_here

"Component not found" errors:

bashCopy code
# Check available components first
# Use grafana_ui tool with action: "list_components" via your MCP client
# Component names are case-sensitive (e.g., "Button", not "button")

"Command not found" errors:

bashCopy code
# Solution: Install Node.js 18+ and ensure npx is available
node --version  # Should be 18+
npx --version   # Should work

Network/proxy issues:

bashCopy code
# Set proxy if needed
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
npx @shelldandy/grafana-ui-mcp-server

Debug Mode

Enable verbose logging:

bashCopy code
# Set debug environment variable
DEBUG=* npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token

🚀 Development

bashCopy code
# Clone the repository
git clone https://github.com/shelldandy/grafana-ui-mcp-server.git
cd grafana-ui-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Test the package
npm run test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📖 Documentation
• 📦 npm Package

🔗 Related Projects

• Grafana UI - The component library this server provides access to
• Grafana - The main Grafana repository
• Model Context Protocol - The protocol specification
• MCP TypeScript SDK - Official MCP SDK

⭐ Acknowledgments

• Grafana Team for the amazing UI component library
• Anthropic for the Model Context Protocol specification
• The open source community for inspiration and contributions

Made with ❤️ by shelldandy

Star ⭐ this repo if you find it helpful!