SR P3 MCP Server

A Model Context Protocol (MCP) server that provides access to Sveriges Radio's P3 channel music playlists. This server enables AI assistants to fetch current and historical playlist data from P3, Sweden's popular music radio station.

Features

• Real-time Current Playlist: Get the currently playing song, previous song, and next song on P3
• Historical Playlist Search: Search P3's playlist history by date or date range (last 90 days)
• Artist Filtering: Filter historical results by artist name
• Rate Limiting: Built-in rate limiting (10 requests/minute) to respect SR's infrastructure
• Input Validation: Robust input validation using Zod schemas
• Error Handling: User-friendly error messages with graceful degradation

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn

Setup

1. Clone this repository:

git clone https://github.com/tomellen/mcpsrtest.git
cd mcpsrtest

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

Usage

Configuring with Claude Desktop

To use this server with Claude Desktop, you need to add it to your Claude Desktop configuration:

1. Build the server (see Installation above)

2. Find your Claude Desktop config file:

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

3. Add the server to your config:

{
  "mcpServers": {
    "sr-p3": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcpsrtest/dist/server.js"
      ]
    }
  }
}

4. Restart Claude Desktop

See CONFIGURATION.md for detailed setup instructions, including platform-specific examples.

Running Locally

Start the server:

npm start

The server runs on stdio transport, suitable for local deployment (including Raspberry Pi).

Development Mode

For development with auto-rebuild:

npm run watch

In another terminal:

npm run dev

MCP Tools

1. get_p3_current_playlist

Fetch the currently playing song on SR P3.

Parameters: None

Returns:

• Current song with artist, title, album, timestamps
• Previous song
• Next song

Example Response:

{
  "songs": [
    {
      "title": "Song Title",
      "artist": "Artist Name",
      "albumName": "Album Name",
      "startTimeUTC": "2024-12-15T10:30:00Z",
      "stopTimeUTC": "2024-12-15T10:33:45Z",
      "duration": 225
    }
  ],
  "metadata": {
    "channel": "P3",
    "channelId": 164,
    "timestamp": "2024-12-15T10:32:00Z",
    "query": {
      "type": "current"
    }
  }
}

2. search_p3_playlist_by_date

Search P3 playlist history for a specific date or date range.

Parameters:

• date (required): ISO 8601 date string or date range
  • Single date: "2024-12-15"
  • Date range: "2024-12-01 to 2024-12-31"
• artist_filter (optional): Filter by artist name (case-insensitive)
• limit (optional): Max songs to return (default: 25, max: 100)

Validation:

• Date must be within last 90 days
• Future dates are rejected
• Date format must be ISO 8601

Example Request:

{
  "date": "2024-12-15",
  "artist_filter": "Taylor Swift",
  "limit": 10
}

Example Response:

{
  "songs": [
    {
      "id": "song-0",
      "title": "Anti-Hero",
      "artist": "Taylor Swift",
      "albumName": "Midnights",
      "startTimeUTC": "2024-12-15T08:15:00Z",
      "stopTimeUTC": "2024-12-15T08:18:30Z",
      "duration": 210
    }
  ],
  "metadata": {
    "channel": "P3",
    "channelId": 164,
    "timestamp": "2024-12-15T10:00:00Z",
    "query": {
      "type": "date-range",
      "startDate": "2024-12-15T00:00:00Z",
      "endDate": "2024-12-15T23:59:59Z",
      "artistFilter": "Taylor Swift",
      "limit": 10
    }
  }
}

Technical Details

P3 Channel ID

The P3 channel ID is hardcoded as 164 in the server. This is Sveriges Radio's official channel identifier for P3.

API Integration

This server uses Sveriges Radio's Open API:

• Base URL: https://api.sr.se/api/v2/playlists/
• No authentication required
• All requests are read-only
• Responses are in JSON format

Rate Limiting

The server implements rate limiting to respect SR's infrastructure:

• Maximum 10 requests per minute
• Tracked per server instance
• Returns helpful error messages when limit is exceeded

Error Handling

All errors are converted to user-friendly messages:

• Network timeouts: "Request timed out. Please try again."
• API unavailable: "Service may be temporarily unavailable."
• Invalid dates: Clear explanation of valid date range
• Rate limit: "Please wait X seconds before trying again."

Security

• All user inputs validated with Zod schemas
• No API keys or secrets required
• Date inputs sanitized and validated
• No raw API URLs exposed in errors
• Request logging to stderr (not stdout)

Project Structure

SRMCP/
├── src/
│   ├── server.ts              # Main MCP server
│   ├── api-client.ts          # SR API client with rate limiting
│   ├── types.ts               # TypeScript interfaces
│   └── tools/
│       ├── current-playlist.ts    # get_p3_current_playlist tool
│       └── search-playlist.ts     # search_p3_playlist_by_date tool
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Development

Building

npm run build

Type Checking

TypeScript is configured with strict mode enabled. All code is fully typed.

Logging

Server logs are written to stderr (not stdout, which is reserved for MCP protocol). This allows for debugging without interfering with the MCP communication.

Deployment

Raspberry Pi

This server is designed for Raspberry Pi deployment:

1. Ensure Node.js 18+ is installed
2. Clone and build the project
3. Run with npm start
4. Configure your MCP client to connect via stdio

Docker (Optional)

A Dockerfile can be added for containerized deployment if needed.

Testing

Basic functionality test:

npm test

This runs the server and verifies it starts without errors.

API Reference

For more information about Sveriges Radio's Open API:

• SR Open API Documentation

License

MIT

Contributing

Contributions are welcome! Please ensure:

• All inputs are validated
• Error messages are user-friendly
• Code follows TypeScript best practices
• Tests pass before submitting PRs

Support

For issues or questions:

• GitHub Issues: github.com/tomellen/mcpsrtest/issues

Acknowledgments

Built with:

• @modelcontextprotocol/sdk - MCP SDK
• Zod - Input validation
• Axios - HTTP client
• fast-xml-parser - XML parsing

Data provided by Sveriges Radio's Open API.