READMEmain

MCP Backstage Server

Name: mcp-backstage
Author: merlindorin

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to query and retrieve information from your Backstage catalog.

Features

Entity Retrieval: Get detailed information about specific entities by kind, namespace, and name
Search: Search across all entities in the Backstage catalog
Authentication: Support for bearer token authentication
SSE Communication: Real-time Server-Sent Events for MCP protocol

Quick Start

1. Install

# Pull from GitHub Container Registry
docker pull ghcr.io/merlindorin/mcp-backstage:latest

# Or build from source
git clone https://github.com/merlindorin/mcp-backstage
cd mcp-backstage
./build.sh

# Or build Docker image locally
docker build -t mcp-backstage .

2. Configure Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "backstage": {
      "command": "/path/to/mcp-backstage",
      "args": ["serve", "--backstage-url", "https://your-backstage.com"],
      "env": {
        "BACKSTAGE_TOKEN": "your-api-token"
      }
    }
  }
}

3. Restart Claude Desktop

4. Use in Claude

"Show me all frontend components"
"Get details about the user-service component"
"Search for APIs related to authentication"

Prerequisites

Go 1.21+ or Docker
Access to a Backstage instance with catalog API enabled
(Optional) Backstage API token for authentication

Running the Server

# Using binary
./mcp-backstage serve --backstage-url="https://your-backstage.com"

# Using Docker (from GHCR)
docker run --rm -it ghcr.io/merlindorin/mcp-backstage:latest serve --backstage-url="https://your-backstage.com"

# Using Docker (local build)
docker run --rm -it mcp-backstage serve --backstage-url="https://your-backstage.com"

# With authentication
export BACKSTAGE_TOKEN="your-api-token"
./mcp-backstage serve --backstage-url="https://your-backstage.com"

Configuration Options

Flag	Environment Variable	Description	Default
`--addr`	-	Server listening address	`:8080`
`--backstage-url`	`BACKSTAGE_URL`	Backstage API URL (required)	-
`--token`	`BACKSTAGE_TOKEN`	API authentication token	-

Available Tools

backstage_get_entity

Get detailed information about a specific Backstage entity.

kind (required): Entity kind (Component, System, API, Resource, User, Group)
namespace (optional): Entity namespace (defaults to "default")
name (required): Entity name

backstage_search

Search across all entities in the Backstage catalog.

term (required): Search term

Advanced Configuration

Multiple Backstage Instances

{
  "mcpServers": {
    "backstage-prod": {
      "command": "/path/to/mcp-backstage",
      "args": ["serve", "--backstage-url", "https://prod.backstage.com"],
      "env": { "BACKSTAGE_TOKEN": "prod-token" }
    },
    "backstage-dev": {
      "command": "/path/to/mcp-backstage",
      "args": ["serve", "--backstage-url", "https://dev.backstage.com"],
      "env": { "BACKSTAGE_TOKEN": "dev-token" }
    }
  }
}

Docker Deployment

The Docker image is available on GitHub Container Registry: https://github.com/merlindorin/mcp-backstage/pkgs/container/mcp-backstage

# Pull from GHCR
docker pull ghcr.io/merlindorin/mcp-backstage:latest

# Run container
docker run -d \
  -e BACKSTAGE_URL=https://your-backstage.com \
  -e BACKSTAGE_TOKEN=your-token \
  -p 8080:8080 \
  ghcr.io/merlindorin/mcp-backstage:latest serve

# Build image locally
docker build -t mcp-backstage .

# Multi-arch build
docker buildx build --platform linux/amd64,linux/arm64 -t mcp-backstage .

Development

Testing

./mcp-backstage test --backstage-url="https://your-backstage.com" --token="your-token"

Project Structure

mcp-backstage/
├── api/v1/           # API client and types
├── cmd/              # CLI application
├── internal/         # Internal packages
│   ├── client/       # Backstage HTTP client
│   ├── logger/       # Logging utilities
│   └── mcptools/     # MCP tool implementations
├── build.sh          # Build script
├── Dockerfile        # Container image definition
└── go.mod            # Go module definition

Troubleshooting

Claude doesn't see the tools

Check configuration file location and JSON syntax
Restart Claude Desktop
Verify binary path is correct

Connection issues

Verify Backstage URL is accessible
Check authentication token
View MCP logs in Claude Desktop (Settings → Developer)

License

MIT