File size: 4,327 Bytes
a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 18dc43e a372367 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 | ---
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.
|