A
licenseNot graded
qualityD
maintenanceIntegrates with Spotify Web API through the Model Context Protocol, allowing users to search tracks, control playback, and manage playlists programmatically.
38
MIT
Spotify MCP
by arikhi14
Provides tools for securely interacting with and analyzing a user's Spotify data, including planned OAuth 2.0 authorization, read-only access to profile, playlists, saved tracks, top tracks/artists, recently played, playlist creation/mutation, and higher-level listening analytics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Spotify MCPshow me my top 10 tracks from the past month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Spotify MCP
A Model Context Protocol (MCP) server for securely interacting with and analyzing a user's Spotify data.
Status: Phase 1 scaffold. Spotify OAuth and Web API integrations come next.
Why this project
The goal is to build more than a thin API wrapper. The finished server will combine MCP tooling, Spotify OAuth 2.0, typed API clients, pagination, rate-limit handling, caching, analytics, tests, and CI.
Related MCP server: Spotify MCP Server
Current functionality
MCP Python SDK v2 server
server_statusdiagnostic toolinstallable Python package
automated test
GitHub Actions CI
secrets-safe repository structure
Requirements
Python 3.10+
uvrecommended
Setup
git clone <your-repo-url>
cd spotify-mcp
uv sync --extra devRun the tests:
uv run pytestOpen the server in the MCP Inspector:
uv run mcp dev src/spotify_mcp/server.pyOr run the stdio server directly:
uv run spotify-mcpRoadmap
Spotify OAuth 2.0 authorization and refresh-token storage
Read-only tools: profile, playlists, saved tracks, top tracks/artists, recently played
Playlist creation and mutation tools
Pagination, retry/backoff, caching, and structured errors
Higher-level listening analytics
Broader tests, documentation, packaging, and MCP Registry publishing
Security
Never commit Spotify credentials or OAuth tokens. Copy .env.example to .env locally when Spotify authorization is added.
License
MIT
Available Tools
1 toolserver_statusA
Return basic server health and Spotify connection state.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| status | Yes | |
| version | Yes | |
| spotify_connected | Yes |
TDQS
A3.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Return' strongly implies a side-effect-free read, and it names the two state areas covered (server health, Spotify connection), but it does not state auth requirements, whether the call can fail, or whether a disconnected Spotify state is surfaced as data vs. an error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, restatement of the name, or redundant qualifiers. Every word contributes to identifying the returned state.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be enumerated, and the description correctly focuses on what is covered. It is nearly complete for a zero-param read tool, with only the failure/disconnected-state behavior left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax for the description to clarify or for the schema to omit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description pairs a specific verb ('Return') with a specific resource ('basic server health and Spotify connection state'), so an agent knows exactly what it retrieves. There are no sibling tools to differentiate from, which is the only reason this is not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: 'server health' signals a diagnostic/health-check call, but the description never says when to invoke it or what condition it addresses. With no siblings and no parameters, no alternatives or exclusions are needed, so the implied context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v0.1.0- First observed
server_status
TDQS
A3.5/5.0
Scored across 1 tool
Disambiguation5/5
There is only one tool, so there is no ambiguity or overlap with other tools. An agent can tell exactly what server_status does.
Naming Consistency5/5
With a single tool, there are no conflicting naming conventions to compare. server_status uses clear, consistent snake_case formatting.
Tool Count1/5
A Spotify MCP server with only one health-check tool is an extreme mismatch for the likely domain scope. This is far too few tools to support meaningful Spotify interactions.
Completeness1/5
The surface contains only a server health/status check and no Spotify operations such as search, playlists, playback, or library access. It is severely incomplete for a Spotify MCP server.
Related MCP Connectors
Builds narrated, playable music stories, explores sample lineage, and saves verified playlists.
Spotify MCP — Web API via client_credentials OAuth
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Personal context and preferences for AI via OAuth-approved profile sections and taste data.
Related MCP Servers
- FlicenseAqualityDmaintenanceA Model Context Protocol server that enables AI assistants like Claude Desktop to interact with Spotify's music streaming service, supporting playback control, playlist management, music search, and user profile access.412-
- FlicenseNot gradedqualityDmaintenanceEnables remote interaction with Spotify through the Model Context Protocol, allowing users to search tracks, control playback, and manage playlists with per-user OAuth authentication. It is hosted on Cloudflare Workers and supports remote MCP over HTTP for compatible clients.2-
- FlicenseNot gradedqualityCmaintenanceEnables natural-language creation, management, and optimization of Spotify playlists via MCP tools like search, generate, analyze, and recommend.-