### Install and Run Suno MCP Server (Bash)

Source: https://github.com/sandraschi/suno-mcp/blob/main/CONTRIBUTING.md

This snippet demonstrates the basic commands to clone the Suno MCP Server repository, install its dependencies using npm, run tests, and start the development server.

```bash
git clone https://github.com/sandraschi/suno-mcp.git
cd suno-mcp
npm install
npm test
npm run dev
```

--------------------------------

### Claude Desktop Suno Integration: Basic Generation

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Demonstrates a basic integration of Claude Desktop with Suno using the `suno_generate_track` tool. This example shows how to initiate track creation with a specific prompt directly from the Claude interface.

```python
Use the suno_generate_track tool to create: "dreamy synthwave with Japanese vocals about futuristic Vienna"
```

--------------------------------

### Claude Desktop Suno Integration: Iterative Refinement

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Illustrates iterative refinement of a Suno-generated track using Claude Desktop. This example highlights how to use stem generation and other studio tools to modify and enhance an existing track.

```python
Generate initial track, then use suno_studio_generate_stem to add specific elements:
- Replace drums with more atmospheric version
- Add guitar solo in bridge section
- Adjust vocal delivery to be more emotional
- Fine-tune mix levels and effects
```

--------------------------------

### Configure Claude Desktop MCP Server with JSON

Source: https://github.com/sandraschi/suno-mcp/blob/main/README.md

Configuration examples in JSON format for integrating the Suno-MCP server with Claude Desktop. It shows how to specify the command, arguments, and environment variables for different operating systems (Windows, macOS/Linux) and installation methods.

```json
{
  "mcpServers": {
    "suno-mcp": {
      "command": "python",
      "args": ["-m", "suno_mcp.server"],
      "env": {
        "PYTHONPATH": "D:\\Dev\\repos\\suno-mcp\\src"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "suno-mcp": {
      "command": "python",
      "args": ["-m", "suno_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/suno-mcp/src"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "suno-mcp": {
      "command": "suno-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

--------------------------------

### Suno Studio Arrangement Prompts

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Examples of prompts for generating specific sections of a synthwave track, such as intro, verse, chorus, bridge, and outro. These prompts guide the AI in creating structural elements and transitions.

```text
Sparse atmospheric intro, building tension, subtle synth pads, distant echoes, establishing neon city mood
```

```text
Driving verse with vocal melody, supporting synth chords, rhythmic bass foundation, building energy
```

```text
Epic chorus climax, layered vocals, soaring synth leads, powerful drum hits, emotional peak
```

```text
Atmospheric bridge, stripped back arrangement, ethereal textures, emotional vocal delivery, tension building
```

```text
Fading outro, sustaining synth pads, vocal echoes, gradual reverb increase, nostalgic fade out
```

--------------------------------

### Install Dependencies and Browsers with Bash

Source: https://github.com/sandraschi/suno-mcp/blob/main/README.md

This snippet shows the bash commands to install project dependencies using pip and to install the necessary Playwright browsers (Chromium) for browser automation.

```bash
cd D:\Dev\repos\suno-mcp
pip install -r requirements.txt

playwright install chromium
```

--------------------------------

### Suno Studio Stem Generation Prompts

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Provides examples for generating specific stems (vocals, drums, bass, synth lead) for synthwave tracks. These prompts focus on the sonic characteristics of individual instrument groups.

```text
Ethereal female vocals in Japanese style, soft and dreamy delivery, slight reverb, emotional expression, clean recording
```

```text
80s inspired drum machine beats, gated reverb, punchy kick, crisp snares, atmospheric cymbals, cyberpunk rhythm
```

```text
Deep analog synthesizer bass, sliding notes, retro wave patterns, warm saturation, driving rhythm section
```

```text
Bright synthesizer melody, Juno-style timbres, arpeggiated sequences, lush chorus effect, nostalgic 80s sound
```

--------------------------------

### Get Suno MCP Server Help (Python)

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Provides multilevel help information for the Suno MCP server, including tool descriptions, usage examples, and available features at different detail levels. The `level` parameter controls the verbosity of the help information.

```python
# Basic help
help(level="basic")

# Response:
# 🎵 **Suno MCP Server Help**
#
# **Available Tool Categories:**
```

--------------------------------

### Prompt Engineering Tips for Synthwave

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Illustrates prompt engineering best practices for synthwave generation, emphasizing specificity, musical elements, contextual details, and iteration strategy. This section provides guidance on how to refine prompts for better results.

```text
Vague: "synthwave song"
Better: "80s inspired synthwave with female vocals"
Best: "dreamy synthwave ballad with Japanese female vocals, analog synthesizers, gated reverb drums"
```

```text
Instrumentation: Specify instruments and timbres
Style references: "Juno-106 style", "analog warmth"
Production techniques: "gated reverb", "tape saturation"
Emotional qualities: "ethereal", "mysterious", "driving"
```

```text
Setting: "futuristic Vienna", "neon city", "cyberpunk"
Mood: "dreamy", "atmospheric", "energetic"
Era: "80s inspired", "retro", "nostalgic"
```

```text
1. Start broad: Basic genre and mood
2. Add details: Specific instruments and techniques
3. Refine: Adjust based on results
4. Layer: Build complex arrangements step by step
```

--------------------------------

### Install Suno MCP Python Package and Dependencies

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Install the Suno MCP server and its dependencies, including Playwright for browser automation. This process involves cloning the repository, installing requirements, and setting up necessary browser binaries.

```bash
# Clone repository
git clone https://github.com/sandra/suno-mcp.git
cd suno-mcp

# Install dependencies
pip install -r requirements.txt

# Or install with pip
pip install -e .

# Install Playwright browsers
playwright install chromium

# Test installation
python -m suno_mcp.server

# Run FastAPI server
python -c "from suno_mcp.server import main_api; main_api()"
# Server runs at http://localhost:3000
# API docs at http://localhost:3000/api/docs
```

--------------------------------

### GET /api/v1/tools

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Lists all available MCP tools with their descriptions and categories.

```APIDOC
## GET /api/v1/tools

### Description
Lists all available MCP tools with their descriptions and categories.

### Method
GET

### Endpoint
`/api/v1/tools`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:3000/api/v1/tools
```

### Response
#### Success Response (200)
- **tools** (array) - A list of available tools.
  - **name** (string) - The name of the tool.
  - **description** (string) - A brief description of the tool.
  - **category** (string) - The category the tool belongs to (e.g., "basic", "studio").

#### Response Example
```json
{
  "tools": [
    {
      "name": "suno_open_browser",
      "description": "Open browser and navigate to Suno AI create page",
      "category": "basic"
    },
    {
      "name": "suno_login",
      "description": "Login to Suno AI account",
      "category": "basic"
    },
    {
      "name": "suno_generate_track",
      "description": "Generate a new music track using Suno AI",
      "category": "basic"
    },
    {
      "name": "suno_download_track",
      "description": "Download a generated track from Suno AI library",
      "category": "basic"
    },
    {
      "name": "suno_get_status",
      "description": "Get current Suno AI session status",
      "category": "basic"
    },
    {
      "name": "suno_close_browser",
      "description": "Close the browser session",
      "category": "basic"
    }
  ]
}
```
```

--------------------------------

### Claude Desktop Suno Integration: Studio Workflow

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Outlines a multi-step studio workflow using Claude Desktop and Suno tools for project creation, stem generation, arrangement, and export. This showcases a more complex, integrated production process.

```python
1. suno_studio_create_project with name "Vienna Synthwave"
2. suno_studio_generate_stem for vocals: "ethereal Japanese female vocals"
3. suno_studio_generate_stem for drums: "80s gated reverb beats"
4. suno_studio_generate_stem for bass: "deep analog synth bass"
5. suno_studio_arrange_track to position stems on timeline
6. suno_studio_export_project as final mix
```

--------------------------------

### Help

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Provides multilevel help information for the Suno MCP server including tool descriptions, usage examples, and available features at different detail levels.

```APIDOC
## help

### Description
Provides multilevel help information for the Suno MCP server.

### Method
GET

### Endpoint
/help

### Parameters
#### Query Parameters
- **level** (string) - Optional - The detail level of help information to retrieve (e.g., 'basic', 'detailed'). Defaults to 'basic'.

### Request Example
```
GET /help?level=detailed
```

### Response
#### Success Response (200)
- **help_text** (string) - The help information content.

#### Response Example
```json
{
  "help_text": "🎵 **Suno MCP Server Help**\n\n**Available Tool Categories:**\n- suno_open_browser\n- suno_login\n- suno_generate_track\n- suno_download_track\n- suno_get_status\n- suno_close_browser\n\nUse 'help?level=detailed' for more information on each tool."
}
```
```

--------------------------------

### Advanced Synthwave Prompting Techniques

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Demonstrates advanced prompting for synthwave by specifying multiple musical elements, instrumentation, and emotional direction. These prompts allow for more granular control over the generated music.

```text
Synthwave track featuring:
- Driving synthesizer bass line
- Atmospheric pads and textures
- Japanese female vocal melodies
- Retro video game sound effects
- Neon-drenched city atmosphere
```

```text
80s style synthwave with:
- Roland Juno-106 style leads
- Deep analog bass
- Gated reverb drums
- Ethereal female vocals
- Arpeggiated synth sequences
```

```text
Emotional synthwave ballad with:
- Slow, dreamy tempo
- Introspective Japanese vocals
- Cinematic string arrangements
- Warm analog synthesizers
- Nostalgic 80s production style
```

--------------------------------

### Structured Logging Example (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/MCP_PRODUCTION_CHECKLIST.md

Shows how to replace `print()` statements with structured logging using Python's `logging` module. This is crucial for maintainability and debugging in production.

```python
import logging
from fastmcp import FastMCP

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

mcp = FastMCP()

@mcp.tool()
def log_example(message: str):
    logger.info(f"Received message: {message}")
    return {"status": "logged"}

# Example of error logging
@mcp.tool()
def error_prone_tool():
    try:
        result = 1 / 0
    except ZeroDivisionError as e:
        logger.error(f"Division by zero occurred: {e}", exc_info=True)
        raise

```

--------------------------------

### Suno AI Music Generation Workflow with JavaScript

Source: https://github.com/sandraschi/suno-mcp/blob/main/README.md

A JavaScript example demonstrating a typical workflow for interacting with the Suno AI music generation service. It covers opening the browser, logging in, generating a track with specified parameters, checking status, downloading the track, and closing the browser.

```javascript
// 1. Open browser and navigate to Suno
suno_open_browser({headless: false})

// 2. Login to your account  
suno_login({
  email: "your-email@example.com",
  password: "your-password"
})

// 3. Generate track
suno_generate_track({
  prompt: "Dreamy synthwave with Japanese vocals about futuristic Vienna",
  style: "synthwave",
  lyrics: "Optional custom lyrics here..."
})

// 4. Check status
suno_get_status()

// 5. Download when ready
suno_download_track({
  track_id: "generated-track-id",
  download_path: "D:\\Music\\Suno_Downloads",
  include_stems: true
})

// 6. Cleanup
suno_close_browser()
```

--------------------------------

### Basic Synthwave Track Generation

Source: https://github.com/sandraschi/suno-mcp/blob/main/prompts/synthwave-examples.md

Generates a basic synthwave track with specified vocals and setting. This prompt focuses on core elements like genre, vocal style, and thematic location.

```text
Create a dreamy synthwave track with Japanese-style female vocals about futuristic Vienna
```

```text
Synthwave track with heavy reverb, driving bass line, ethereal female vocals in Japanese, neon city atmosphere, 80s inspired synthesizer melodies
```

```text
Atmospheric synthwave with mysterious vibe, Japanese female vocals, futuristic Vienna setting, neon lights, cyberpunk aesthetic
```

--------------------------------

### FastAPI Test Client Example (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/MCP_PRODUCTION_CHECKLIST.md

Demonstrates using FastAPI's `TestClient` to make HTTP requests to API endpoints for testing purposes. This is essential for testing the FastAPI interface of the MCP server.

```python
from fastapi.testclient import TestClient
from your_main_app_file import app  # Assuming your FastAPI app is in 'your_main_app_file.py'

client = TestClient(app)

def test_read_main():
    response = client.get('/api/v1/items/1')
    assert response.status_code == 200
    assert response.json() == {'item_id': 1, 'name': 'Sample Item'}

def test_create_item():
    response = client.post('/api/v1/items/', json={'name': 'New Item', 'price': 99.99})
    assert response.status_code == 200
    assert response.json() == {'name': 'New Item', 'price': 99.99}

```

--------------------------------

### Configure Claude Desktop with Suno MCP Server

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Set up Claude Desktop to use Suno MCP by adding the server configuration to the `claude_desktop_config.json` file. This involves specifying the command and arguments to run the Suno MCP server, either directly or via an installed package.

```json
// Windows: %APPDATA%/Claude/claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "suno-mcp": {
      "command": "python",
      "args": ["-m", "suno_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/suno-mcp/src"
      }
    }
  }
}

// Alternative using installed package:
{
  "mcpServers": {
    "suno-mcp": {
      "command": "suno-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

--------------------------------

### Advanced Suno Studio Workflow in JavaScript

Source: https://github.com/sandraschi/suno-mcp/blob/main/README.md

This JavaScript code snippet demonstrates a full workflow within Suno Studio. It covers opening the studio, creating a new project, generating multiple audio stems (vocals, drums, bass) with specific prompts and parameters, waiting for their completion, arranging tracks on a timeline, setting the project's BPM, defining song sections, applying audio effects like reverb, adjusting volume, and finally exporting the project in WAV format with stems and MIDI included. The workflow concludes with closing the studio session.

```javascript
// 1. Open Suno Studio
suno_studio_open({headless: false})

// 2. Create new project
suno_studio_create_project({
  name: "My Vienna Synthwave Project",
  template: "electronic",
  bpm: 120,
  key: "C"
})

// 3. Generate multiple stems
suno_studio_generate_stem({
  prompt: "Dreamy synthwave lead with Japanese-style vocals",
  type: "vocals",
  position: 0,
  duration: 120,
  mood: "mysterious"
})

suno_studio_generate_stem({
  prompt: "Driving synthwave drums with heavy reverb",
  type: "drums",
  position: 0,
  duration: 120
})

suno_studio_generate_stem({
  prompt: "Deep analog bass line in C minor",
  type: "bass",
  position: 0,
  duration: 120
})

// 4. Wait for generations to complete
suno_studio_wait_generation({generationId: "generation-id-1"})
suno_studio_wait_generation({generationId: "generation-id-2"})
suno_studio_wait_generation({generationId: "generation-id-3"})

// 5. Arrange tracks on timeline
suno_studio_arrange_track({
  trackId: "track-1",
  startTime: 0,
  endTime: 120,
  loop: true
})

// 6. Set project BPM
suno_studio_set_bpm({bpm: 128})

// 7. Create song sections
suno_studio_create_sections({
  sections: [
    {name: "Intro", startTime: 0, endTime: 16},
    {name: "Verse", startTime: 16, endTime: 48},
    {name: "Chorus", startTime: 48, endTime: 80},
    {name: "Outro", startTime: 80, endTime: 120}
  ]
})

// 8. Mix and master
suno_studio_adjust_volume({
  trackId: "track-1",
  volume: 85
})

suno_studio_add_effect({
  trackId: "track-1",
  effect: "reverb",
  parameters: {roomSize: 0.7, wetDry: 30}
})

// 9. Export final project
suno_studio_export_project({
  format: "wav",
  quality: "lossless",
  includeStems: true,
  includeMIDI: true,
  downloadPath: "D:\\Music\\Suno_Studio_Exports"
})

// 10. Cleanup
suno_studio_close({saveSession: true})
```

--------------------------------

### Export Section

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Export a specific section of the project with defined start and end times.

```APIDOC
## POST /suno_studio_export_section

### Description
Export a specific section of the project as an audio file.

### Method
POST

### Endpoint
/suno_studio_export_section

### Parameters
#### Path Parameters
- **sectionName** (string) - Required - The name of the section to export.

#### Query Parameters
- **startTime** (number) - Optional - Start time in seconds.
- **endTime** (number) - Optional - End time in seconds.
- **format** (string) - Optional - Export format. Enum: ["mp3", "wav", "flac"]. Default: "mp3"
- **downloadPath** (string) - Optional - Download directory path. Default: "D:\\Dev\\repos\\temp"

### Request Example
```json
{
  "sectionName": "Verse 1",
  "startTime": 30.5,
  "endTime": 60.0,
  "format": "flac",
  "downloadPath": "/path/to/section_exports"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of section export initiation.

#### Response Example
```json
{
  "message": "Section export initiated successfully."
}
```
```

--------------------------------

### Get Generation Status

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Check the status of a specific audio generation using its unique ID.

```APIDOC
## GET /suno_studio_get_generation_status

### Description
Get the status of a specific generation by its ID.

### Method
GET

### Endpoint
/suno_studio_get_generation_status

### Parameters
#### Query Parameters
- **generationId** (string) - Required - The ID of the generation to check.

### Request Example
```
GET /suno_studio_get_generation_status?generationId=gen_123
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the generation (e.g., "Pending", "In Progress", "Completed", "Failed").
- **progress** (number) - The completion progress in percentage (if applicable).

#### Response Example
```json
{
  "status": "Completed",
  "progress": 100
}
```
```

--------------------------------

### Get Studio Status

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Retrieve the comprehensive status of the Suno Studio, including generation, project, and track information.

```APIDOC
## GET /suno_studio_get_status

### Description
Get comprehensive Studio status, optionally including generation, project, and track details.

### Method
GET

### Endpoint
/suno_studio_get_status

### Parameters
#### Query Parameters
- **includeGenerations** (boolean) - Optional - Include active generation status. Default: true
- **includeProject** (boolean) - Optional - Include current project info. Default: true
- **includeTracks** (boolean) - Optional - Include track information. Default: true

### Request Example
```
GET /suno_studio_get_status?includeGenerations=false&includeTracks=false
```

### Response
#### Success Response (200)
- **status** (object) - Overall studio status information.
- **generations** (array) - List of active generation statuses (if requested).
- **project** (object) - Information about the current project (if requested).
- **tracks** (array) - List of track information (if requested).

#### Response Example
```json
{
  "status": "Operational",
  "generations": [
    {
      "id": "gen_123",
      "progress": 50,
      "status": "In Progress"
    }
  ],
  "project": {
    "name": "My Awesome Project"
  },
  "tracks": [
    {
      "id": "track_abc",
      "name": "Lead Vocal"
    }
  ]
}
```
```

--------------------------------

### End-to-End Music Generation Workflow with Suno MCP

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Demonstrates a complete music generation pipeline using Suno MCP tools. This includes initializing the browser, authenticating with Suno AI, generating a track based on a prompt, checking its status, downloading the result, and cleaning up resources.

```python
# Complete workflow using MCP tools via Claude Desktop

# Step 1: Initialize browser session
suno_open_browser(headless=False)  # Use False for debugging

# Step 2: Authenticate with Suno AI
suno_login(
    email="your-email@suno.ai",
    password="your-secure-password"
)

# Step 3: Generate a custom track
suno_generate_track(
    prompt="Cinematic orchestral piece with epic brass and strings, building to a powerful climax",
    style="classical",
    duration="long"
)

# Step 4: Check generation status
suno_get_status()
# Wait for generation to complete (typically 1-3 minutes)

# Step 5: Download the completed track
suno_download_track(
    track_id="generated-track-uuid",
    download_path="exports/orchestral/",
    include_stems=True
)

# Step 6: Clean up resources
suno_close_browser()
```

--------------------------------

### Arrange Track

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Arranges a specified track on the timeline by setting its start and end times, and configuring looping and fades.

```APIDOC
## POST /api/arrange_track

### Description
Arranges a track on the project timeline. You can specify the start and end times, enable looping, and set fade-in/fade-out durations.

### Method
POST

### Endpoint
/api/arrange_track

### Parameters
#### Request Body
- **trackId** (string) - Required - The ID of the track to arrange.
- **startTime** (number) - Required - The start time of the track in seconds.
- **endTime** (number) - Optional - The end time of the track in seconds. If not provided, the track plays until its natural end.
- **loop** (boolean) - Optional - Whether to loop the track. Defaults to false.
- **fadeIn** (number) - Optional - The duration of the fade-in effect in seconds. Defaults to 0.
- **fadeOut** (number) - Optional - The duration of the fade-out effect in seconds. Defaults to 0.

### Request Example
```json
{
  "trackId": "track_123",
  "startTime": 15.5,
  "endTime": 60.0,
  "loop": true,
  "fadeIn": 1.0,
  "fadeOut": 2.0
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the track was arranged.

#### Response Example
```json
{
  "message": "Track track_123 arranged successfully."
}
```
```

--------------------------------

### GET /api/v1/status

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Returns current server and browser session status including authentication state and active page information.

```APIDOC
## GET /api/v1/status

### Description
Returns current server and browser session status including authentication state and active page information.

### Method
GET

### Endpoint
`/api/v1/status`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:3000/api/v1/status
```

### Response
#### Success Response (200)
- **browser_open** (boolean) - Indicates if the browser session is open.
- **page_ready** (boolean) - Indicates if the browser page is ready.
- **current_url** (string) - The current URL displayed in the browser.
- **page_title** (string) - The title of the current browser page.
- **in_studio** (boolean) - Indicates if the studio mode is active.
- **server_mode** (string) - The current server mode (e.g., "dual").

#### Response Example
```json
{
  "browser_open": true,
  "page_ready": true,
  "current_url": "https://app.suno.ai/create/",
  "page_title": "Suno - Make Music",
  "in_studio": false,
  "server_mode": "dual"
}
```
```

--------------------------------

### FastMCP Initialization and Tool Registration (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/MCP_PRODUCTION_CHECKLIST.md

Demonstrates the basic structure for initializing a FastMCP application and registering tools. It emphasizes a thin `server.py` with imports from a structured `tools/` directory.

```python
from fastmcp import FastMCP

# Import tools from structured directories
from tools.category1.tools import Category1Tools
from tools.category2.tools import Category2Tools

# Initialize FastMCP app
mcp = FastMCP()

# Register tools using add_tools
mcp.add_tools(Category1Tools)
mcp.add_tools(Category2Tools)

# FastAPI app is implicitly handled by FastMCP
# app = mcp.app

# Additional FastAPI configurations can be added here if needed

```

--------------------------------

### Create Sections

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Defines and creates distinct sections within the song, such as verses, choruses, and bridges, with specified start and end times.

```APIDOC
## POST /api/create_sections

### Description
Creates song sections like verses, choruses, or bridges on the timeline. Each section is defined by its name, start time, and end time.

### Method
POST

### Endpoint
/api/create_sections

### Parameters
#### Request Body
- **sections** (array) - Required - An array of section objects, each containing:
  - **name** (string) - Required - The name of the section (e.g., 'Verse 1', 'Chorus').
  - **startTime** (number) - Required - The start time of the section in seconds.
  - **endTime** (number) - Required - The end time of the section in seconds.
  - **repeat** (number) - Optional - The number of times this section should repeat. Defaults to 1.

### Request Example
```json
{
  "sections": [
    {
      "name": "Intro",
      "startTime": 0,
      "endTime": 15,
      "repeat": 1
    },
    {
      "name": "Verse 1",
      "startTime": 15,
      "endTime": 45,
      "repeat": 1
    },
    {
      "name": "Chorus",
      "startTime": 45,
      "endTime": 75,
      "repeat": 2
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the sections were created.

#### Response Example
```json
{
  "message": "Song sections created successfully."
}
```
```

--------------------------------

### GET /health

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Health check endpoint returning server status and uptime information. Used for monitoring and load balancer health checks.

```APIDOC
## GET /health

### Description
Health check endpoint returning server status and uptime information. Used for monitoring and load balancer health checks.

### Method
GET

### Endpoint
`/health`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:3000/health
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the server (e.g., "ok").
- **version** (string) - The server version.
- **uptime** (float) - The server uptime in seconds.
- **tools_loaded** (integer) - The number of tools loaded by the server.

#### Response Example
```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600.5,
  "tools_loaded": 23
}
```
```

--------------------------------

### Launch Suno Studio DAW Interface (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/HALLUCINATED_STUDIO_TOOLS.md

Attempts to launch the Suno Studio DAW interface. It uses placeholder selectors for Studio detection and assumes the ability to navigate to the studio URL. This function is non-functional without Premier access and real interface inspection.

```python
await page.goto("https://app.suno.ai/studio/")
# Fake selectors for Studio detection
await page.locator('[data-testid*="studio"], .studio-interface').wait_for()
```

--------------------------------

### Arrange Track on Timeline with Suno Studio

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Arranges a specified track on the timeline by setting its start and end times. It supports looping and fade-in/fade-out durations.

```javascript
{
  name: "suno_studio_arrange_track",
  description: "Arrange tracks on the timeline",
  inputSchema: {
    type: "object",
    properties: {
      trackId: {
        type: "string",
        description: "Track ID to arrange"
      },
      startTime: {
        type: "number",
        description: "Start time in seconds"
      },
      endTime: {
        type: "number",
        description: "End time in seconds"
      },
      loop: {
        type: "boolean",
        description: "Loop the track",
        default: false
      },
      fadeIn: {
        type: "number",
        description: "Fade in duration in seconds",
        default: 0
      },
      fadeOut: {
        type: "number",
        description: "Fade out duration in seconds",
        default: 0
      }
    },
    required: ["trackId", "startTime"]
  }
}
```

--------------------------------

### Load Existing Studio Project (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/HALLUCINATED_STUDIO_TOOLS.md

Aims to load an existing Suno Studio project using a provided project ID. It employs a list of potential selectors to find and click the project. This functionality is purely theoretical as the actual project listing and selection mechanism is unknown.

```python
# Fake project browser
project_selectors = [
    f'[data-project-id="{project_id}"]',
    f'[data-testid="project-{project_id}"]',
    f'button:has-text("{project_id}")'
]
await SelectorHelper.try_selectors(page, project_selectors, "click")
```

--------------------------------

### FastAPI Health Check Endpoint (Python)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/MCP_PRODUCTION_CHECKLIST.md

An example of a simple health check endpoint for a FastAPI application, returning a JSON status. This is a requirement for MCP server conformance.

```python
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get('/health')
def health_check():
    return JSONResponse(content={'status': 'OK'})

```

--------------------------------

### Get Suno Studio Generation Status (JavaScript)

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Fetches the status of a specific generation within Suno Studio, identified by its unique generation ID. This is a required parameter.

```javascript
{
  name: "suno_studio_get_generation_status",
  description: "Get status of specific generation",
  inputSchema: {
    type: "object",
    properties: {
      generationId: {
        type: "string",
        description: "Generation ID"
      }
    },
    required: ["generationId"]
  }
}
```

--------------------------------

### List Available Tools Endpoint (Bash)

Source: https://context7.com/sandraschi/suno-mcp/llms.txt

Lists all available MCP tools, providing their names, descriptions, and categories. This endpoint is essential for discovering the functionalities offered by the Suno MCP.

```bash
curl -X GET http://localhost:3000/api/v1/tools
```

--------------------------------

### Create Song Sections with Suno Studio

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Creates song sections such as verse, chorus, or bridge on the timeline. Each section requires a name, start time, and end time, and can be configured to repeat.

```javascript
{
  name: "suno_studio_create_sections",
  description: "Create song sections (verse, chorus, bridge)",
  inputSchema: {
    type: "object",
    properties: {
      sections: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            startTime: { type: "number" },
            endTime: { type: "number" },
            repeat: { type: "number", default: 1 }
          },
          required: ["name", "startTime", "endTime"]
        }
      }
    },
    required: ["sections"]
  }
}
```

--------------------------------

### Open Suno Studio Session - JavaScript

Source: https://github.com/sandraschi/suno-mcp/blob/main/docs/suno-studio-mcp-enhancement-plan.md

Initializes and opens Suno Studio, allowing for optional headless mode and session restoration. It configures the browser viewport for the studio session.

```javascript
{
  name: "suno_studio_open",
  description: "Open Suno Studio and initialize session",
  inputSchema: {
    type: "object",
    properties: {
      headless: {
        type: "boolean",
        description: "Run browser in headless mode",
        default: true
      },
      restoreSession: {
        type: "boolean",
        description: "Restore previous session if available",
        default: true
      },
      viewport: {
        type: "object",
        properties: {
          width: { type: "number", default: 1920 },
          height: { type: "number", default: 1080 }
        }
      }
    }
  }
}
```