MCP_instructions.md

metadata

title: Demo MIT - MCP Server
emoji: 💻
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false

---

Spotify MCP Server

Spotify MCP (Model Context Protocol) server, implemented with FastAPI + FastMCP. It authenticates a Spotify account via OAuth2 and exposes MCP tools to query profile data, search tracks, read library/recent playback, and manage playlists.

Target Deployment (Hugging Face)

This server runs in the Space:

• pharmaia/Demo_MCP_Server_Spotify
• https://huggingface.co/spaces/pharmaia/Demo_MCP_Server_Spotify

Public base URL:

• https://pharmaia-demo-mcp-server-spotify.hf.space

Public MCP SSE endpoint:

• https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse

General Architecture

• FastAPI exposes HTTP endpoints for healthcheck and OAuth flow.
• FastMCP registers MCP tools and publishes them over SSE.
• httpx performs calls to Spotify Accounts API (tokens) and Spotify Web API (data/actions).
• spotify_tokens.json (or a configurable path) stores tokens and expiration metadata.

Authentication Flow

1. The client opens /auth/login.
2. The server generates an anti-CSRF state and redirects to Spotify /authorize.
3. Spotify redirects to /auth/callback with code + state.
4. The server validates state, exchanges code for tokens, and saves them.
5. MCP tools use the stored token; if expired, the server attempts automatic refresh.

HTTP Endpoints (Production)

• GET /: basic service metadata and useful routes.
• GET /health: simple status (ok).
• GET /auth/status: local token status.
• GET /auth/reset: removes local token (forces re-authentication).
• GET /auth/login?force=true: starts OAuth (with consent dialog).
• GET /auth/callback: Spotify OAuth callback.
• SSE /gradio_api/mcp/sse: MCP SSE transport (mounted by FastMCP).

Main MCP Tools

• spotify_auth_status: authentication status.
• spotify_get_auth_url: direct OAuth authorization URL.
• spotify_get_my_profile: current user profile.
• spotify_search_tracks: track search.
• spotify_list_saved_tracks: saved tracks.
• spotify_list_recently_played: recently played tracks.
• spotify_get_top_tracks: top tracks by time range.
• spotify_check_saved_tracks: checks whether tracks are saved.
• spotify_save_tracks / spotify_remove_saved_tracks / spotify_set_tracks_saved.
• spotify_list_my_playlists: user playlists.
• spotify_create_playlist: create playlist.
• spotify_add_items_to_playlist: add items.
• spotify_update_playlist_details: update metadata.
• spotify_replace_playlist_items: replace content.
• spotify_delete_playlist: delete (unfollow) playlist.

Environment Variables (Hugging Face Spaces)

Configure in Space Settings > Variables and secrets:

• SPOTIFY_CLIENT_ID
• SPOTIFY_CLIENT_SECRET
• SPOTIFY_REDIRECT_URI = https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback
• SPOTIFY_SCOPES (optional; the server appends required scopes)
• SPOTIFY_TOKEN_FILE (optional; default spotify_tokens.json)
• MCP_PUBLIC_SSE_URL = https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse
• PORT (optional; default 7860)

Important: in Spotify Developer Dashboard, the Redirect URI must match exactly:

• https://pharmaia-demo-mcp-server-spotify.hf.space/auth/callback

Production Usage (HF Space)

1. Open OAuth login:

• https://pharmaia-demo-mcp-server-spotify.hf.space/auth/login

2. Complete Spotify consent.
3. Check status:

• https://pharmaia-demo-mcp-server-spotify.hf.space/auth/status

4. Connect MCP client to the public SSE endpoint:

• https://pharmaia-demo-mcp-server-spotify.hf.space/gradio_api/mcp/sse

Local Run (Optional)

1. Install dependencies:

pip install -r requirements.txt

2. Start the server:

python app.py

3. Open in browser:

• http://localhost:7860/auth/login

4. Connect MCP client to local SSE endpoint:

• http://localhost:7860/gradio_api/mcp/sse

Design Notes

• The server keeps OAuth state in memory with TTL to prevent callback replay.
• Scopes are validated for sensitive playlist operations.
• Spotify IDs/URIs/URLs are normalized before API calls.
• Spotify responses are transformed into compact payloads for MCP tool consumption.