# Spotify MCP

A Model Context Protocol (MCP) server for securely interacting with and analyzing a user's Spotify data.

> Status: Phase 1 scaffold. Spotify OAuth and Web API integrations come next.

## Why this project

The goal is to build more than a thin API wrapper. The finished server will combine MCP tooling, Spotify OAuth 2.0, typed API clients, pagination, rate-limit handling, caching, analytics, tests, and CI.

## Current functionality

- MCP Python SDK v2 server
- `server_status` diagnostic tool
- installable Python package
- automated test
- GitHub Actions CI
- secrets-safe repository structure

## Requirements

- Python 3.10+
- `uv` recommended

## Setup

```bash
git clone <your-repo-url>
cd spotify-mcp
uv sync --extra dev
```

Run the tests:

```bash
uv run pytest
```

Open the server in the MCP Inspector:

```bash
uv run mcp dev src/spotify_mcp/server.py
```

Or run the stdio server directly:

```bash
uv run spotify-mcp
```

## Roadmap

1. Spotify OAuth 2.0 authorization and refresh-token storage
2. Read-only tools: profile, playlists, saved tracks, top tracks/artists, recently played
3. Playlist creation and mutation tools
4. Pagination, retry/backoff, caching, and structured errors
5. Higher-level listening analytics
6. Broader tests, documentation, packaging, and MCP Registry publishing

## Security

Never commit Spotify credentials or OAuth tokens. Copy `.env.example` to `.env` locally when Spotify authorization is added.

## License

MIT