Bandmate MCP Server

An MCP (Model Context Protocol) server that provides access to the Bandmate REST API for managing songs and lists with chord notations.

Installation

cd bandmate-mcp
npm install
npm run build

Configuration

Set the following environment variables:

Variable	Description	Default
`BANDMATE_API_URL`	Base URL for the Bandmate API	`https://vertigox.ue.r.appspot.com/api`
`BANDMATE_AUTH_TOKEN`	Firebase auth token for authenticated endpoints	(empty)

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude/mcp_settings.json):

{
  "mcpServers": {
    "bandmate": {
      "command": "node",
      "args": ["/path/to/bandmate-mcp/dist/index.js"],
      "env": {
        "BANDMATE_API_URL": "https://vertigox.ue.r.appspot.com/api",
        "BANDMATE_AUTH_TOKEN": "your-firebase-token"
      }
    }
  }
}

Or using npx (after publishing):

{
  "mcpServers": {
    "bandmate": {
      "command": "npx",
      "args": ["bandmate-mcp"],
      "env": {
        "BANDMATE_AUTH_TOKEN": "your-firebase-token"
      }
    }
  }
}

Available Tools

Song Tools

Tool	Description
`get_songs`	Get songs (public or filtered by userId/ids)
`get_song`	Get a single song by ID
`get_songs_by_user`	Get all songs created by a specific user
`get_songs_in_list`	Get all songs in a specific list
`upsert_song`	Create or update a song
`search_songs`	Search songs by title or tags

List Tools

Tool	Description
`get_lists`	Get lists (public or filtered by userId)
`get_list`	Get a single list by ID
`upsert_list`	Create or update a list (requires auth)

Tool Parameters

get_songs

userId (optional): Filter to user's songs + public songs
ids (optional): Comma-separated song IDs to fetch

get_song

id (required): Song ID

get_songs_by_user

userId (required): User ID

get_songs_in_list

listId (required): List ID

upsert_song

id (optional): Song ID for updates
title (required): Song title
chordsText (required): Chord notation and lyrics
isPublic (optional): Public visibility (default: false)
bpm (optional): Beats per minute
key (optional): Musical key
voice (optional): Vocal range
tags (optional): Array of tags
spotifyUrl (optional): Spotify link
youtubeUrl (optional): YouTube link
userId (optional): Creator user ID

get_lists

userId (optional): Filter to user's lists + public lists

get_list

id (required): List ID

upsert_list

id (optional): List ID for updates
name (optional): List name
isPrivate (optional): Private visibility (default: false)
songs (optional): Array of song IDs
userId (optional): Owner user ID

search_songs

query (required): Search term
userId (optional): Include user's private songs

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start

Deployment to Google Cloud Run

This MCP server uses SSE (Server-Sent Events) transport, making it deployable as a remote HTTP service.

Prerequisites

Install the Google Cloud CLI
Authenticate: gcloud auth login
Set your project: gcloud config set project YOUR_PROJECT_ID

Deploy

# Build and deploy in one command
gcloud run deploy bandmate-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "BANDMATE_API_URL=https://vertigox.ue.r.appspot.com/api"

# Or with authentication token
gcloud run deploy bandmate-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "BANDMATE_API_URL=https://vertigox.ue.r.appspot.com/api,BANDMATE_AUTH_TOKEN=your-token"

Using the Remote MCP Server

Once deployed, you'll get a URL like https://bandmate-mcp-xxxxx-uc.a.run.app.

Endpoints

Endpoint	Method	Description
`/`	GET	Service info
`/health`	GET	Health check
`/sse`	GET	SSE connection for MCP
`/messages`	POST	Client-to-server messages

With Claude Desktop (Remote SSE)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "bandmate": {
      "url": "https://bandmate-mcp-xxxxx-uc.a.run.app/sse"
    }
  }
}

Local Docker Testing

# Build the image
docker build -t bandmate-mcp .

# Run locally
docker run -p 8080:8080 \
  -e BANDMATE_API_URL=https://vertigox.ue.r.appspot.com/api \
  bandmate-mcp

# Test health endpoint
curl http://localhost:8080/health

CI/CD with GitHub Actions

The repository includes automatic deployment to Cloud Run on every push to main.

Setup

Create a GCP Service Account with the following roles:
- Cloud Run Admin
- Cloud Build Editor
- Storage Admin
- Service Account User

Create a JSON key for the service account:

gcloud iam service-accounts keys create key.json \
  --iam-account=YOUR_SA@YOUR_PROJECT.iam.gserviceaccount.com

Add the secret to GitHub:
- Go to your repo → Settings → Secrets and variables → Actions
- Create a new secret named GCP_SA_KEY
- Paste the contents of key.json
Delete the local key file:
```
rm key.json
```

Now every push to main will automatically deploy to Cloud Run.

License

MIT

bandmate-mcp