ArtistLens

A powerful Model Context Protocol (MCP) server that provides access to the Spotify Web API and Last.fm API. ArtistLens enables seamless interaction with Spotify's music catalog and Last.fm's music database, including searching for tracks, albums, and artists, as well as accessing artist-specific information like top tracks and related artists.

Current Version: 0.1.13

Installation

Installing via Smithery

To install ArtistLens for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @superseoworld/artistlens --client claude

Manual Installation

You can install the package globally:

npm install -g @thomaswawra/artistlens

Or run it directly with npx:

npx -y @thomaswawra/artistlens

Configuration

Add to your MCP settings file (e.g., claude_desktop_config.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "artistlens": {
      "command": "npx",
      "args": ["-y", "@thomaswawra/artistlens"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "LASTFM_API_KEY": "your_lastfm_api_key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

API Credentials

You'll need to provide your API credentials:

1. For Spotify:
   • Go to Spotify Developer Dashboard
   • Create a new application
   • Get your Client ID and Client Secret
2. For Last.fm:
   • Go to Last.fm API Accounts
   • Create a new API account
   • Get your API Key
3. Add them to the configuration as shown above

Endpoint Configuration

You can configure which endpoints are enabled or disabled in two ways:

1. Through Environment Variable: Add the configuration to your MCP settings file:

{
  "mcpServers": {
    "artistlens": {
      "command": "npx",
      "args": ["-y", "@thomaswawra/artistlens"],
      "env": {
        "SPOTIFY_CLIENT_ID": "your_client_id",
        "SPOTIFY_CLIENT_SECRET": "your_client_secret",
        "LASTFM_API_KEY": "your_lastfm_api_key",
        "ARTISTLENS_CONFIG": "{\"endpoints\":{\"spotify\":{\"search\":false,\"artists\":true},\"lastfm\":{\"artists\":true}}}"
      }
    }
  }
}

2. Through Configuration File: Create a configuration file (e.g., artistlens.config.json):

{
  "endpoints": {
    "spotify": {
      "search": {
        "search": true,
        "get_available_genres": true,
        "get_new_releases": true,
        "get_recommendations": true
      },
      "artists": {
        "get_artist": true,
        "get_multiple_artists": true,
        "get_artist_top_tracks": true,
        "get_artist_related_artists": true,
        "get_artist_albums": true
      },
      "albums": {
        "get_album": true,
        "get_album_tracks": true
      },
      "tracks": {
        "get_track": true
      },
      "audiobooks": {
        "get_audiobook": true,
        "get_multiple_audiobooks": true,
        "get_audiobook_chapters": true
      },
      "playlists": {
        "get_playlist": true,
        "get_playlist_tracks": true,
        "get_playlist_items": true,
        "modify_playlist": true,
        "add_tracks_to_playlist": true,
        "remove_tracks_from_playlist": true,
        "get_current_user_playlists": true,
        "get_featured_playlists": true,
        "get_category_playlists": true
      }
    },
    "lastfm": {
      "artists": {
        "get_lastfm_artist_info": true,
        "get_lastfm_artist_top_tracks": true,
        "get_lastfm_artist_similar": true,
        "get_lastfm_artist_top_albums": true,
        "get_lastfm_artist_tags": true,
        "search_lastfm_artist": true,
        "get_lastfm_top_artists": true,
        "get_lastfm_top_tracks": true,
        "get_lastfm_geo_top_artists": true,
        "get_lastfm_geo_top_tracks": true,
        "get_lastfm_album_info": true,
        "search_lastfm_album": true
      }
    }
  }
}

Then use it when initializing the server:

const config = require('./artistlens.config.json');
const server = new ArtistLensServer(config);

Configuration Options

Each endpoint category can be configured at two levels:

1. Category Level:

   • Set the entire category to true or false to enable/disable all endpoints in that category
   • Example: "artists": true enables all artist-related endpoints

2. Method Level:

   • Configure individual methods within each category
   • Example: "get_artist_related_artists": false disables only the related artists endpoint

Default Configuration

By default, all endpoints are enabled if not specified in the configuration. You only need to specify the endpoints you want to disable by setting them to false.

Implications of Disabling Endpoints

• Disabled endpoints will not appear in the available tools list
• Attempts to call disabled endpoints will result in an error message
• Other enabled endpoints will continue to function normally
• The configuration can be updated at runtime by restarting the server

Features

Spotify Integration

• Search for tracks, albums, artists, and playlists
• Get artist information including top tracks and related artists
• Get album information and tracks
• Access new releases and recommendations
• Get audiobook information with market-specific content and chapters
• Note: Audiobook endpoints may require additional authentication or market-specific access
• Get and modify playlist information (name, description, public/private status)
• Access playlist tracks and items with pagination support
• Support for both Spotify IDs and URIs
• Automatic token management with client credentials flow

Last.fm Integration

• Get detailed artist information including biography and statistics
• Get artist's top tracks with play counts and listeners
• Find similar artists based on Last.fm's listening data
• Get artist's top albums with play counts
• Get artist tags and genres
• Search for artists and albums with pagination support
• Access global top artists and tracks charts with pagination
• Access country-specific top artists and tracks with pagination
• Access Last.fm's rich metadata and community data

Available Tools

Spotify Tools

• get_access_token: Get a valid Spotify access token
• search: Search for tracks, albums, artists, or playlists
• get_artist: Get artist information
• get_artist_top_tracks: Get an artist's top tracks
• get_artist_related_artists: Get artists similar to a given artist
• get_artist_albums: Get an artist's albums
• get_album: Get album information
• get_album_tracks: Get an album's tracks
• get_track: Get track information
• get_available_genres: Get a list of available genres for recommendations
• get_new_releases: Get new album releases
• get_recommendations: Get track recommendations based on seed tracks, artists, or genres
• get_audiobook: Get audiobook information with optional market parameter
• get_multiple_audiobooks: Get information for multiple audiobooks (max 50)
• get_audiobook_chapters: Get chapters of an audiobook with pagination support (1-50 chapters per request)
• get_playlist: Get a playlist owned by a Spotify user
• get_playlist_tracks: Get full details of the tracks of a playlist (1-100 tracks per request)
• get_playlist_items: Get full details of the items of a playlist (1-100 items per request)
• modify_playlist: Change playlist details (name, description, public/private state, collaborative status)
• add_tracks_to_playlist: Add one or more tracks to a playlist with optional position
• remove_tracks_from_playlist: Remove one or more tracks from a playlist with optional positions and snapshot ID
• get_current_user_playlists: Get a list of the playlists owned or followed by the current Spotify user (1-50 playlists per request)
• get_featured_playlists: Get a list of Spotify featured playlists with optional locale and pagination support
• get_category_playlists: Get a list of Spotify playlists tagged with a particular category

Last.fm Tools

• get_lastfm_artist_info: Get Last.fm information about an artist
• get_lastfm_artist_top_tracks: Get Last.fm top tracks for an artist
• get_lastfm_artist_similar: Get Last.fm similar artists
• get_lastfm_artist_top_albums: Get Last.fm top albums for an artist
• get_lastfm_artist_tags: Get Last.fm tags for an artist
• search_lastfm_artist: Search for artists on Last.fm
• get_lastfm_top_artists: Get Last.fm global top artists chart with pagination support
• get_lastfm_top_tracks: Get Last.fm global top tracks chart with pagination support
• get_lastfm_geo_top_artists: Get Last.fm top artists by country with pagination support
• get_lastfm_geo_top_tracks: Get Last.fm top tracks by country with pagination support
• get_lastfm_album_info: Get detailed information about an album including tracklist, tags, and stats
• search_lastfm_album: Search for albums on Last.fm with pagination support