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.
- 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
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.
All operations are performed through one tool with an action
parameter:
{
"tool": "grafana_ui",
"arguments": {
"action": "get_component",
"componentName": "Button"
}
}
Core Component Actions:
get_component
- Get TypeScript source code for any Grafana UI componentget_demo
- Get Storybook demo files showing component usagelist_components
- List all available Grafana UI componentsget_metadata
- Get component props, exports, and metadataget_directory
- Browse the Grafana UI repository structure
Advanced Grafana Actions:
get_documentation
- Get rich MDX documentation with sections and examplesget_stories
- Get parsed Storybook stories with interactive controlsget_tests
- Get test files showing usage patterns and edge casessearch
- Search components by name and optionally by documentation contentget_theme_tokens
- Get Grafana design system tokens (colors, typography, spacing, etc.)get_dependencies
- Get component dependency tree analysis (shallow or deep)
- 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
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 thegrafana_ui
tool with anaction
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.
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!
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
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
-
Go to GitHub Settings:
-
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)
-
Copy Your Token:
- Copy the generated token (starts with
ghp_
) β οΈ Save it securely - you won't see it again!
- Copy the generated token (starts with
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"
}
}
}
}
# 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
NEW: Work with a local Grafana repository for faster development and access to uncommitted changes!
- β‘ 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
-
Clone the Grafana Repository:
git clone https://github.com/grafana/grafana.git cd grafana
-
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
-
Claude Desktop Configuration:
{ "mcpServers": { "grafana-ui": { "command": "npx", "args": ["@shelldandy/grafana-ui-mcp-server"], "env": { "GRAFANA_REPO_PATH": "/path/to/your/grafana/repository" } } } }
The server checks sources in this order:
- Local Repository (
--grafana-repo-path
orGRAFANA_REPO_PATH
) - GitHub API with Token (
--github-api-key
orGITHUB_*_TOKEN
) - GitHub API without Token (rate limited to 60 requests/hour)
- 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"
)
# 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"
The MCP server provides the unified grafana_ui
tool for AI assistants:
// 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"
}
}
// 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 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
}
}
// 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
}
}
Add to your Claude Desktop configuration (~/.config/Claude/claude_desktop_config.json
):
{
"mcpServers": {
"grafana-ui": {
"command": "npx",
"args": [
"@shelldandy/grafana-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
Or with environment variable:
{
"mcpServers": {
"grafana-ui": {
"command": "npx",
"args": ["@shelldandy/grafana-ui-mcp-server"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}
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
{
"mcp": {
"grafana-ui": {
"command": "npx",
"args": [
"@shelldandy/grafana-ui-mcp-server",
"--github-api-key",
"ghp_your_token_here"
]
}
}
}
{
"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.
Grafana UI components follow a rich multi-file structure:
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.
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
"Rate limit exceeded" errors:
# Solution: Add GitHub API token
npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token_here
"Component not found" errors:
# 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:
# Solution: Install Node.js 18+ and ensure npx is available
node --version # Should be 18+
npx --version # Should work
Network/proxy issues:
# Set proxy if needed
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
npx @shelldandy/grafana-ui-mcp-server
Enable verbose logging:
# Set debug environment variable
DEBUG=* npx @shelldandy/grafana-ui-mcp-server --github-api-key ghp_your_token
# 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
This project is licensed under the MIT License - see the LICENSE file for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
- π Report Issues
- π¬ Discussions
- π Documentation
- π¦ npm Package
- 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
- 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!