# naunau75/spotify_mcp architecture

> Architecture diagram of the GitHub repository naunau75/spotify_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naunau75/spotify_mcp
- Repository: https://github.com/naunau75/spotify_mcp

## Overview

##### Project Type and Purpose
- The project is an MCP server designed to connect Claude (the client) with Spotify.
- It leverages Spotipy’s API to control playback, search for music, and manage Spotify’s queue.
- The README highlights that this is a server component for an MCP (Model Context Protocol) that integrates with Spotify via spotify_api functions.

##### File Structure
- Top-Level Files/Directories:
- Files like .cursorrules, .gitignore, .python-version, and pyproject.toml indicate standard configuration and project metadata.
- The presence of uv.lock and directions for building/publishing with uv commands suggest usage of a package management and build tooling system.
- The src Directory:
- src/spotify_mcp contains the core Python modules:
- server.py – likely contains the entry point or the logic to accept commands from Claude.
- spotify_api.py – encapsulates API calls to Spotify (using the Spotipy library).
- utils.py – provides supporting functions or helper routines.
- The structure indicates a modular design where the MCP server logic, Spotify-specific API interactions, and utility functions are separated.
- Other Elements:
- A log file (spotify_mcp.log) under both the root and inside src/spotify_mcp.
- A media directory shows demo-related assets, including a video and an article.
- The architecture.md file might hold additional internal documentation regarding internal architecture (if needed, review it for extra details).

##### README for Additional Insights
- Key Features section clarifies the Spotify functionalities: playback control, search, info fetching, queue management.
- Instructions for configuration and running locally show that the project expects Spotify API keys, command line arguments through uv, and integration with Claude’s config.
- The deployment and debugging sections describe the workflow, recommending the MCP Inspector for debugging and note that the MCP uses stdio for communication.

##### Final Remarks
- That the annotations refer to key decisions like the use of environmental configuration for Spotify API keys, the reliance on Spotipy for API interactions, and the modular design of the application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        client["MCP Client (Claude)"]:::external
    end

    subgraph "Server Architecture"
        server["MCP Server"]:::server
        api["Spotify API Module"]:::module
        util["Utility Module"]:::module
    end

    subgraph "External Services"
        spotify["External Spotify Service"]:::external
    end

    subgraph "Infrastructure"
        log_root["Logging (root)"]:::logging
        log_src["Logging (src)"]:::logging
        build_py["Build Config (pyproject.toml)"]:::build
        build_uv["Build Config (uv.lock)"]:::build
    end

    client -->|"sendsCommand"| server
    server -->|"executesApiCall"| api
    server -->|"usesUtil"| util
    api -->|"callsSpotifyAPI"| spotify
    server -->|"logsTo"| log_root
    server -->|"logsTo"| log_src
    build_py -.->|"builds"| server
    build_uv -.->|"builds"| server

    click server "https://github.com/naunau75/spotify_mcp/blob/main/src/spotify_mcp/server.py"
    click api "https://github.com/naunau75/spotify_mcp/blob/main/src/spotify_mcp/spotify_api.py"
    click util "https://github.com/naunau75/spotify_mcp/blob/main/src/spotify_mcp/utils.py"
    click log_root "https://github.com/naunau75/spotify_mcp/blob/main/spotify_mcp.log"
    click log_src "https://github.com/naunau75/spotify_mcp/blob/main/src/spotify_mcp/spotify_mcp.log"
    click build_py "https://github.com/naunau75/spotify_mcp/blob/main/pyproject.toml"
    click build_uv "https://github.com/naunau75/spotify_mcp/blob/main/uv.lock"

    classDef external fill:#FFCCCC,stroke:#AA0000,stroke-width:2px;
    classDef server fill:#CCEEFF,stroke:#0055AA,stroke-width:2px;
    classDef module fill:#CCFFCC,stroke:#009900,stroke-width:2px;
    classDef logging fill:#FFFFCC,stroke:#999900,stroke-width:2px;
    classDef build fill:#FFEEAA,stroke:#CC6600,stroke-width:2px;
```
