suno-mcp 0.1.0

MCP server for Suno AI music generation using your suno.com account (no third-party API)

Suno MCP

MCP server for generating music with your suno.com account — no third-party API keys, no 2Captcha, no extra paid services.

Use it from Cursor, Claude Desktop, or any MCP-compatible client to check credits, generate songs, and download MP3s.

Features

• Your Suno account — uses your existing subscription/credits
• No API middlemen — authenticates via Clerk in a real browser session
• Generation tools — custom lyrics/style or simple prompt mode
• Library access — credits, recent songs, status polling, MP3 download

Requirements

• Python 3.10+
• A free or paid Suno account at suno.com
• Chromium (installed via Playwright)

Quick Start

Install from PyPI

pip install suno-mcp
playwright install chromium
cp .env.example .env  # optional — defaults work out of the box

Install from source

git clone https://github.com/David-J-Shibley/suno-mcp.git
cd suno-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium
cp .env.example .env

First run: A browser window opens. Log into Suno if prompted. Your session is saved to ~/.suno-mcp/browser-profile.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "suno": {
      "command": "/absolute/path/to/suno-mcp/.venv/bin/python",
      "args": ["-m", "suno_mcp"],
      "env": {
        "SUNO_HEADLESS": "false"
      }
    }
  }
}

Set SUNO_HEADLESS to false — the Create button must be visible for generation to work.

Restart the MCP server after config or code changes (Cursor → Settings → MCP).

macOS Homebrew Python note

If pip fails with a pyexpat / libexpat error on macOS Tahoe, add to your MCP env:

"DYLD_LIBRARY_PATH": "/opt/homebrew/opt/expat/lib"

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suno": {
      "command": "/absolute/path/to/suno-mcp/.venv/bin/python",
      "args": ["-m", "suno_mcp"],
      "env": {
        "SUNO_HEADLESS": "false"
      }
    }
  }
}

Tools

Tool	Description
suno_get_credits	Check your Suno credit balance
suno_get_recent	List recent songs in your library
suno_generate_song	Custom mode — lyrics + style
suno_generate_from_description	Simple mode — describe the song
suno_check_status	Poll generation status by song ID
suno_wait_for_songs	Wait until songs are ready
suno_download_song	Download MP3 to a folder

How It Works

1. Auth — Reads JWT from window.Clerk.session.getToken() in the logged-in browser tab.
2. Reads (credits, feed, recent) — Direct HTTPS to studio-api.prod.suno.com.
3. Generation — Fills lyrics/style via React state, then dispatches a trusted CDP mouse click on the Create button (required by hCaptcha).

Generation approach adapted from unforced/suno-mcp.

Configuration

Variable	Default	Description
SUNO_BROWSER_PROFILE_DIR	~/.suno-mcp/browser-profile	Persistent browser profile
SUNO_HEADLESS	false	Must be false for generation
SUNO_CDP_URL	—	Connect to existing Chrome via CDP
SUNO_DEBUG	—	Set to 1 for debug logging

Optional: Use Your Own Chrome

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=~/.suno-mcp/chrome-profile

Then in .env:

SUNO_CDP_URL=http://localhost:9222

Log into Suno in that Chrome window.

Troubleshooting

Not signed in — Log into suno.com/create in the browser window the MCP server opens.

Profile already in use — Restart the Suno MCP server in Cursor (only one browser instance per profile).

Empty song IDs after generate — Keep SUNO_HEADLESS=false, ensure the browser window stays visible, and restart the MCP server after updates.

Cookie dialog — Click "Allow All" once if Suno shows a privacy/cookie banner.

Limitations

• Unofficial — Uses Suno's internal endpoints; may break when Suno updates.
• Browser required — Generation needs a visible browser window.
• Uses your Suno credits — Same quota as the website.
• MVP scope — No covers, extends, or stems yet.

Disclaimer

This is an unofficial project and is not affiliated with Suno. Use at your own risk and in accordance with Suno's terms of service.

Contributing

Issues and pull requests are welcome on GitHub.

See PUBLISHING.md for PyPI release instructions.

License

MIT — see LICENSE.