一个模型上下文协议（MCP）服务器，允许MCP客户端搜索Spotify的 曲目目录，并访问连接用户最近播放的曲目。

要求

• Node.js和NPM
• 一个Spotify账号
• 一款在 Spotify 开发者仪表盘

在你的Spotify应用设置中，添加这个精确的重定向URI：

服务器利用Spotify的客户端凭证流程搜索目录， OAuth 授权，带有 user-read-recently-played 读取权限 收听历史。

布置

1. 安装依赖并编译TypeScript源代码：

2. 将你的Spotify应用客户端ID和客户端秘密信息提供给MCP服务器，作为 SPOTIFY_CLIENT_ID 和 SPOTIFY_CLIENT_SECRET。

该仓库包含一个 VS Code MCP 配置 .vscode/mcp.json。当 VS Code 提示服务器输入时，输入 客户端ID和Spotify应用的秘密信息。秘密输入是被掩盖的。

对于另一个MCP客户端，配置一个运行的stdio服务器 node /absolute/path/to/spotify-mcp/build/index.js 并传递两个变量 在那个服务器的环境中。不要提交或放入凭证 源文件。

3. 从你的 MCP 客户端启动 spotify-mcp 服务器。

Spotify MCP

A Model Context Protocol (MCP) server that lets an MCP client search Spotify’s track catalog and access the connected user’s recently played tracks.

Requirements

• Node.js and npm
• A Spotify account
• A Spotify app created in the Spotify Developer Dashboard

In your Spotify app settings, add this exact Redirect URI:

http://127.0.0.1:8080/callback

The server uses Spotify’s client credentials flow to search the catalog, and OAuth authorization with the user-read-recently-played permission to read listening history.

Setup

1. Install dependencies and compile the TypeScript source:

   npm ci
   npm run build
   

2. Provide your Spotify app’s client ID and client secret to the MCP server as SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET.

   This repository includes a VS Code MCP configuration at .vscode/mcp.json. When VS Code prompts for the server inputs, enter the client ID and secret from your Spotify app. The secret input is masked.

   For another MCP client, configure a stdio server that runs node /absolute/path/to/spotify-mcp/build/index.js and pass both variables in that server’s environment. Do not commit credentials or put them in source files.

3. Start the spotify-mcp server from your MCP client. The first time you need listening history, call spotify_connect and open the returned URL in a browser. Once Spotify confirms the connection, return to your MCP client.

The refresh token is saved locally at ~/.config/spotify-mcp/token.json with restrictive file permissions. You normally only need to connect once; use spotify_connect again if access needs to be restored.

Available tools

spotify_connect

Starts Spotify account authorization and returns a URL to open in a browser. The local callback listener uses 127.0.0.1:8080.

search_tracks

Searches Spotify’s track catalog by track, artist, or album terms.

• query (string, required): Search terms.
• limit (integer, optional): Number of results, from 1 to 10; defaults to 5.

Requires both Spotify environment variables. Does not require connecting a user account.

get_recently_played

Returns recently played tracks for the connected Spotify account, including artist, play time, and Spotify link.

• limit (integer, optional): Number of results, from 1 to 50; defaults to 20.
• after (integer, optional): Unix timestamp in milliseconds; return plays after this time.
• before (integer, optional): Unix timestamp in milliseconds; return plays before this time.

Specify at most one of after and before. This tool requires the user to have completed spotify_connect.

Development

The TypeScript source is in src/; npm run build emits runnable JavaScript into build/. The server communicates over stdio, so start it through an MCP client rather than as an interactive command-line application.

License