Provides OAuth-based authentication and playback control for Spotify, including play/pause, track navigation, volume control, device management, and search functionality for artists and songs.
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 MCP Server play Taylor Swift's Love Story"
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 OAuth和MCP协议的Python服务器，提供Spotify音乐控制功能。
✅ Spotify OAuth认证
✅ 获取当前播放状态
✅ 播放/暂停控制
✅ 上一首/下一首切换
✅ 音量控制
✅ 播放位置跳转
✅ 设备管理
Related MCP server: MCP Spotify Server
安装依赖：
pip install -e .配置Spotify OAuth凭据：
创建应用并获取 Client ID 和 Client Secret
设置重定向URI为 http://127.0.0.1:8000/callback
设置环境变量：
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
export SPOTIFY_REDIRECT_URI="http://127.0.0.1:8000/callback" # 可选，默认值服务器通过stdio通信，通常由MCP客户端（如Claude Desktop）自动启动。
调用 spotify_get_auth_url 工具获取授权URL
在浏览器中访问该URL并完成授权
从回调URL中提取授权码（code参数）
调用 spotify_authenticate 工具，传入授权码完成认证
认证信息会保存在 ~/.spotify_mcp_token.json，后续使用会自动刷新token。
认证成功后，可以使用以下工具：
spotify_get_current_playback - 获取当前播放状态
spotify_pause - 暂停播放
spotify_next - 下一首
spotify_previous - 上一首
spotify_set_volume - 设置音量（0-100）
spotify_seek - 跳转到指定位置
spotify_get_devices - 获取可用设备列表
spotify_play_artist - 搜索并播放指定艺术家的top 10 tracks，如 'Taylor Swift的歌曲'
spotify_play_song - 根据歌手和歌曲名播放歌曲。例如：播放 Taylor Swift 的 Love Story
在Claude Desktop的配置文件中添加：
{
"mcpServers": {
"spotify-mcp": {
"command": "python",
"args": ["-m", "spotify_mcp"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI"="http://127.0.0.1:8000/callback"
}
}
}
}或者使用uv
{
"mcpServers": {
"spotify-mcp": {
"command": "uv",
"args": ["run", "-m", "spotify_mcp"],
"env": {
"SPOTIFY_CLIENT_ID": "your_client_id",
"SPOTIFY_CLIENT_SECRET": "your_client_secret",
"SPOTIFY_REDIRECT_URI"="http://127.0.0.1:8000/callback"
}
}
}
}确保Spotify应用已开启并正在播放音乐
某些功能需要Spotify Premium账户
Token会自动刷新，无需手动重新认证
设备ID参数为可选，不指定时使用当前活动设备
MIT
使用授权码完成Spotify OAuth认证。需要先调用spotify_get_auth_url获取授权URL
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 从授权URL回调中获取的授权码 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only states the purpose and prerequisite, but doesn't mention side effects like token storage, session establishment, or failure modes. This is a significant gap for a security-sensitive authentication step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy: the first states the purpose, the second adds the critical prerequisite. Both are essential, and the description is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations. The description fails to explain what the tool returns, what side effects occur (e.g., token persistence), or error behavior. The prerequisite is helpful, but the overall context is incomplete for an OAuth authentication tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains the 'code' parameter as the authorization code from the callback. The description adds no additional semantic meaning beyond restating that, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action (complete Spotify OAuth authentication) and resource (Spotify OAuth), and distinguishes itself from sibling playback tools by referencing the prerequisite spotify_get_auth_url. This makes the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to call spotify_get_auth_url first, establishing a clear sequence. It doesn't list alternatives or exclusions, but for an OAuth flow this is the natural completion step, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取Spotify OAuth授权URL。用户需要访问此URL进行授权，然后将返回的授权码用于spotify_authenticate工具
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the action (getting URL) but does not explicitly state whether it is read-only, side-effect-free, or if any external interaction occurs beyond generating the URL. Since it is a simple retrieval, a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and to the point, with no unnecessary elaboration. It efficiently conveys both the purpose and the next step.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for this simple tool. It explains what the tool returns (the auth URL) and how to use it, making it self-contained despite lacking an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is trivially 100%. The baseline for high coverage is 3, and there is no additional parameter information needed or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving the Spotify OAuth authorization URL. It also distinguishes from the sibling spotify_authenticate by indicating that the URL is for authorization and the code is used in that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the workflow: users must visit the URL for authorization and then use the returned code with spotify_authenticate. This provides clear when-to-use guidance and how to proceed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取当前播放状态，包括当前歌曲、播放进度、设备等信息
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of disclosing side effects and requirements. It implies a read-only operation via 'get', but does not explicitly state that it is non-destructive, whether authentication is required, or what errors may occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately states the action and key result fields. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and expected data, but lacks context around authentication prerequisites, error conditions, and how the optional device_id parameter behaves in different scenarios. Given no output schema and no annotations, a few more contextual details would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the only parameter (device_id) with a minimal description. The tool description adds no extra meaning about how device_id affects the response, but schema coverage is complete, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (current playback state) and the action (get), and specifies the key information included (current song, progress, device). This distinguishes it from sibling tools like pause, next, or get_devices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as authentication. Sibling tools exist for auth and playback control, but the description does not position this tool relative to them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取所有可用的Spotify设备列表
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral details are disclosed. The description does not mention potential side effects, authentication requirements, or the nature of the result (e.g., read-only). Since no annotations are provided, the description carries the full burden but only states the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is perfectly concise and well-structured for the simple purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and no output schema specified, the description is sufficient. It explains the core functionality without overcomplicating, which matches the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to add about parameter meaning. The baseline for 0 parameters is 4, and the description does not need to explain parameters. It is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving the list of all available Spotify devices. It uses a specific verb 'get' and a clear resource 'devices', and it is distinct from sibling tools that handle playback or authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but given its unique purpose among siblings, the context is implicit. No specific scenarios or preconditions are mentioned, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
播放下一首歌曲
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of disclosing side effects. It only states the action 'play next song' without mentioning authentication requirements, the need for an active playback session, or that it changes the current track state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but largely redundant with the tool name 'spotify_next'. It adds minimal informational value beyond what the name already conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should cover context like failure modes (e.g., no active device), prerequisites (e.g., authentication), or side effects. It only provides the basic action, leaving significant contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter 'device_id' with '设备ID（可选）', so schema coverage is 100%. The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '播放下一首歌曲' (Play next song) clearly states the action and resource, and it distinguishes the tool from siblings like spotify_previous and spotify_pause.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
暂停播放
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It simply says 'pause playback' without explaining what happens if no device is specified, whether authentication is needed, or how errors are handled. The tool's side effects are not described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, making it concise and front-loaded. There is no redundant wording. However, it is under-specified, but for conciseness alone it earns a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description is incomplete. It does not explain the effect on playback state, whether device_id defaults to the active device, or any potential errors. An agent would need to infer behavior from the name alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the optional device_id parameter, and schema coverage is 100%. The description does not mention the parameter, but the schema adequately documents it. Baseline 3 applies because the description adds no extra parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '暂停播放' (pause playback) clearly states a specific verb and resource. It is unambiguous that the tool pauses current playback. However, it does not differentiate from siblings like spotify_next or spotify_previous, though the purpose is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites such as an active playback session, or whether to specify a device. No exclusions or alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
搜索并播放指定艺术家的歌曲，如 'Taylor Swift的歌曲'
| Name | Required | Description | Default |
|---|---|---|---|
| artist | Yes | 艺术家名称 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It states the tool plays music (implying a side effect on playback) but does not mention prerequisites like authentication, behavior on artist not found, or whether it interrupts current playback. This is a significant gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and includes a clarifying example. Every word earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is minimal. It omits authentication requirements (given the sibling auth tools), playback behavior (e.g., stopping current track), and error handling. No output description is provided. This is incomplete for a mutation tool with no annotations to fall back on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'artist' parameter (100% coverage). The description adds that the artist is used to search and play their songs, which reinforces the schema but does not add format or syntax details. Baseline 3 is appropriate since the schema already handles the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: search and play songs by a specified artist, with a concrete example ('Taylor Swift的歌曲'). It distinguishes from the sibling spotify_play_song (which likely targets a specific song) by focusing on artist-based playback, giving a specific verb+resource pairing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for playing an artist's songs but does not explicitly state when to use this vs spotify_play_song or other playback controls. There is no mention of alternatives or exclusion conditions; the example offers context but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据歌手和歌曲名播放歌曲。例如：播放 Taylor Swift 的 Love Story
| Name | Required | Description | Default |
|---|---|---|---|
| song | Yes | 歌曲名 | |
| artist | Yes | 歌手名 | |
| device_id | No | 播放设备ID（可选） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for disclosing side effects. It only states 'play a song' without mentioning potential impacts on current playback, requirement for an active device, authentication needs, or error handling. The primary action is clear, but behavioral consequences are not addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with an illustrative example. It contains no redundant information and is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action, the description provides the essential details of what and how. However, it omits any mention of required prerequisites (e.g., authentication or active device), return values, or failure scenarios. Given that the tool interacts with playback state, this lack of context may leave the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the role of 'artist' and 'song' by indicating they identify the song. The 'device_id' parameter is not elaborated, but its schema description already labels it as an optional playback device ID. Overall, the description adds minimal extra meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'play' and the resource 'song' identified by artist and song name, with a concrete example. It effectively distinguishes from the sibling tool 'spotify_play_artist' which focuses on an artist's catalog.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage example but does not explicitly state when to choose this tool over alternatives like 'spotify_play_artist' or when to use 'device_id'. Some guidance is implied by the action, but no explicit conditions or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
播放上一首歌曲
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses no side effects, error conditions, or requirements. It does not state what happens if no previous track exists or if playback is not active. With no annotations, the description bears full responsibility for behavioral transparency, and it falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant information. It is well-structured for its simplicity and delivers the core message efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple action and minimal schema, the description is adequate for the basic purpose but lacks any surrounding context about usage workflow or integration with other Spotify actions. It is not incomplete enough to fail, but it could benefit from brief context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter (device_id as optional), so schema coverage is 100%. The tool description adds no extra meaning beyond the schema, but the baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'play previous song' in Chinese, which is specific and distinct from sibling tools like 'spotify_next' (next) and 'spotify_pause'. It is concise but unambiguous about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites such as authentication, active playback, or device availability. The description offers only the action, leaving the agent without contextual cues for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
跳转到指定播放位置
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） | |
| position_ms | Yes | 目标位置（毫秒） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only states the action without mentioning prerequisites such as active playback, side effects on the current track, or potential failures. No extra context is added beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is entirely purposeful and front-loaded, with no filler. It communicates the essential operation in the simplest possible form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema fully describes parameters, the description lacks any context about the need for active playback, device selection, or what happens on success/failure. It is adequate for a simple seek operation but does not provide richer operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have schema descriptions covering 100% of the parameters, so the description adds no additional parameter semantics. The baseline score of 3 is appropriate because the schema already provides full parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (jump/seek) and the target (specified playback position), effectively distinguishing it from playback control siblings like pause, next, and previous. The verb 'jump' precisely conveys a seek operation, and the resource is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives such as spotify_next or spotify_play_song, leaving the agent to infer the appropriate context. There is no mention of prerequisites like active playback or device selection, nor any exclusionary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
设置音量，范围0-100
| Name | Required | Description | Default |
|---|---|---|---|
| device_id | No | 设备ID（可选） | |
| volume_percent | Yes | 音量百分比（0-100） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'set volume' but does not disclose that this is a mutating operation affecting the active or specified device, whether it requires an active playback session, or what the response looks like. The optional device_id behavior is not explained, leaving ambiguity about the target device.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It front-loads the action and includes the critical range constraint. Every word earns its place, achieving maximum efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with a fully described schema and no output schema, the description is minimally sufficient. However, it omits behavioral details like what happens if no device is specified, whether the volume change is immediate, and any error cases. An agent might not know that the optional device_id defaults to the active device, which is important for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are fully described in the schema (device_id as optional string, volume_percent as integer 0-100 with min/max). The description adds no new semantic information beyond repeating the range, which the schema already provides. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (set volume) and the resource (volume), with an explicit range (0-100). It distinguishes from sibling tools which control playback (pause, next, seek) rather than volume, so an agent can immediately identify this as the volume control tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While there is no explicit mention of alternatives, the purpose is unambiguous: use this to change the volume. The context is clear enough that an agent would not confuse it with other playback controls. However, it does not state any preconditions (e.g., must have an active device) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0spotify_authenticatespotify_get_auth_urlspotify_get_current_playbackspotify_get_devicesspotify_nextspotify_pausespotify_play_artistspotify_play_songspotify_previousspotify_seekspotify_set_volumeScored across 11 tools
Each tool has a clear, distinct purpose: auth, playback control (pause, next, previous, seek, volume), device lookup, and specific play actions. play_artist and play_song differ by target, preventing confusion.
All tools follow a consistent snake_case pattern with the 'spotify_' prefix, and verb phrases accurately describe actions. This makes the naming predictable and readable.
11 tools is well-scoped for a Spotify control server, covering essential playback and auth operations without being excessive or sparse.
The toolset covers core playback controls and auth, but lacks search, playlist management, and track/album details. It could be considered incomplete for a full-featured Spotify integration.
Full Spotify Web API coverage - albums, artists, playlists, player controls, and more.
Spotify MCP — Web API via client_credentials OAuth
Spotify: Spotify Data API for Millions of songs & podcasts, artists, albums, playlists and more.
Write lyrics in 100+ styles, score them, generate full songs with 4 engines, split stems. OAuth.