Spaces:
Sleeping
Sleeping
| 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: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 2. Start the server: | |
| ```bash | |
| 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. | |