diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d8b337a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# mcp-spotify
+
+Python MCP server exposing Spotify library and playlist management as tools for Claude.
+
+## Prerequisites
+
+- **Python 3.11+**
+- **Spotify Developer Account** with an app registered at [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+  - Note the Client ID and Client Secret from your app
+  - Set the Redirect URI to `http://localhost:8888/callback` in your app settings
+
+## Setup
+
+### Step 1: Install dependencies
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+### Step 2: Configure credentials
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and fill in your Spotify credentials:
+
+```
+SPOTIFY_CLIENT_ID=your_client_id_here
+SPOTIFY_CLIENT_SECRET=your_client_secret_here
+```
+
+### Step 3: Authenticate with Spotify
+
+Run the server once with the `--auth` flag to authenticate with Spotify. This will open a browser window where you authorize the app to access your Spotify account. The access token is cached locally at `.cache` in the project directory for subsequent runs.
+
+```bash
+python server.py --auth
+```
+
+You should see: `Authentication successful! Token cached.`
+
+### Step 4: Register with Claude Code
+
+Add the MCP server to your Claude Code configuration by editing `~/.claude/settings.json`:
+
+````json
+{
+  "mcpServers": {
+    "spotify": {
+      "command": "/absolute/path/to/mcp-spotify/.venv/bin/python",
+      "args": ["/absolute/path/to/mcp-spotify/server.py"]
+    }
+  }
+}
+````
+
+**Note:** Replace `/absolute/path/to/mcp-spotify` with the actual path to your project. To find it, run `pwd` in the project directory:
+
+```bash
+cd /path/to/mcp-spotify
+pwd
+```
+
+Then update the paths in `settings.json` accordingly. On Windows, the python path is `.venv\Scripts\python.exe`.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_playlists` | List the authenticated user's Spotify playlists. |
+| `get_playlist_tracks` | Get all tracks in a Spotify playlist with full metadata: name, artists, album, duration, popularity, URI, and added_at. |
+| `list_saved_tracks` | Get the user's liked/saved tracks from Spotify. Optional limit parameter (default 50). |
+| `search_tracks` | Search Spotify for tracks. Returns track URIs that can be passed to add_tracks_to_playlist. |
+| `create_playlist` | Create a new Spotify playlist for the authenticated user. Takes name, optional description, and public flag. |
+| `add_tracks_to_playlist` | Add tracks to a Spotify playlist by their URIs (e.g., `spotify:track:...`). |