SunoMCP

A Model Context Protocol (MCP) server for AI music generation using Suno through the AceDataCloud API.

Generate AI music, lyrics, and manage audio projects directly from Claude, VS Code, or any MCP-compatible client.

Features

• Music Generation - Create AI-generated songs from text prompts
• Custom Lyrics & Style - Full control over lyrics, title, and music style
• Song Extension - Continue existing songs from any timestamp
• Cover/Remix - Create cover versions with different styles
• Lyrics Generation - Generate structured lyrics from descriptions
• Persona Management - Save and reuse voice styles
• Custom Music Models - Create and reuse app-owned custom music models
• Task Tracking - Monitor generation progress and retrieve results

Tool Reference

Connect in minutes

The hosted server is https://suno.mcp.acedata.cloud/mcp. Choose one authentication route before following a client example:

The hosted server always receives a Bearer token: with OAuth, the client obtains and sends it after sign-in; with API-token setup, you supply it. DCR is client registration, not a separate AceDataCloud API key. After consent, the hosted service currently reuses or creates an API credential for your account; it may fail if the account cannot obtain one. Some clients offer a published client identity or manual client ID; those are client-specific alternatives, not a second API-token requirement. Browser sign-in does not remove the need for an AceDataCloud account. Music generation uses your AceDataCloud account and may incur usage charges. Review current Suno pricing and limits before generating.

Browser sign-in: hosted server

Use this path for clients with remote MCP OAuth support. Add only the URL first; do not also set an Authorization header. If a client cannot complete discovery or registration, use the API-token route below.

Claude and Claude Desktop chat

Use Claude's remote custom connector in Customize → Connectors → Add custom connector (or your organization's connector settings). Enter the hosted URL, choose sign-in, and select Register automatically for the OAuth client if Claude asks. Complete the AceDataCloud login and consent flow, then enable the connector in your conversation. Claude Desktop's claude_desktop_config.json is for local MCP processes; it is not where Claude's remote custom connectors are installed. Claude's connector guide.

Claude Code

claude mcp add --transport http --scope user suno https://suno.mcp.acedata.cloud/mcp
claude mcp login suno

In Claude Code, /mcp shows the connection and available tools. For project scope, merge {"mcpServers":{"suno":{"type":"http","url":"https://suno.mcp.acedata.cloud/mcp"}}} into <project>/.mcp.json; keep existing entries when merging. Claude Code and Claude Desktop chat have separate MCP configuration. Claude Code MCP guide.

Cursor

In Cursor's MCP settings, add a remote server with the hosted URL and complete the OAuth prompt. For project scope, merge this into <project>/.cursor/mcp.json; for your own machines, use ~/.cursor/mcp.json:

{
  "mcpServers": {
    "suno": {
      "url": "https://suno.mcp.acedata.cloud/mcp"
    }
  }
}

The URL-only project config contains no token. Do not commit a project config if you later add a real token. Cursor MCP guide.

VS Code with GitHub Copilot

Run MCP: Add Server, choose HTTP, and enter the hosted URL. Save to the user profile for personal use or to a workspace config for a team; approve the server and complete sign-in when prompted. New workspace configs use <project>/.mcp.json; VS Code also reads its .vscode/mcp.json format. This is the VS Code format for a local workspace:

{
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp"
    }
  }
}

Run MCP: List Servers to check connection and tool loading. VS Code MCP setup and configuration reference.

Codex CLI or Codex app

codex mcp add suno --url https://suno.mcp.acedata.cloud/mcp
codex mcp login suno

Codex keeps user MCP settings in ~/.codex/config.toml and can show the server in /mcp. Official Codex MCP guide.

API token: hosted server

Use this route when you need a fixed credential or your client does not complete OAuth. Sign in at AceDataCloud Platform, open the Suno service page, and use Acquire to create or obtain an API token. Store the token privately. A pasted Bearer token bypasses the browser sign-in flow; an invalid header will not automatically fall back to OAuth in Claude Code.

For Claude Code, set the variable in the environment that starts Claude Code, then add the server. The shell expands the token when you add the server, so treat the saved user-level MCP config as a secret; use browser sign-in above if you do not want a key in client config:

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user suno https://suno.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

For a shared project config, put only the variable reference in <project>/.mcp.json and keep the token in each user's environment. Unlike the CLI example above, Claude Code expands ${ACEDATACLOUD_API_TOKEN} when it reads .mcp.json. Merge this entry with existing servers:

{
  "mcpServers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"
      }
    }
  }
}

For Cursor, use its ${env:ACEDATACLOUD_API_TOKEN} syntax in a user-level ~/.cursor/mcp.json (or an uncommitted project config):

{
  "mcpServers": {
    "suno": {
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"
      }
    }
  }
}

For VS Code, prefer a user-profile MCP config and a masked input instead of putting the token in the JSON. Merge these fields into the file opened by MCP: Open User Configuration:

{
  "inputs": [
    {"id": "acedata-suno-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "suno": {
      "type": "http",
      "url": "https://suno.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-suno-token}"}
    }
  }
}

This interactive input is specific to VS Code's user/workspace format; do not copy it into .mcp.json for Agent Host. VS Code prompts once and stores the value securely for later use. VS Code configuration reference.

Other clients use different schemas. For Cline, open MCP Servers → Configure → Configure MCP Servers (Cline CLI: ~/.cline/data/settings/cline_mcp_settings.json) and use type: "streamableHttp" under mcpServers; Cline's guide has the full shape. For JetBrains AI Assistant, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP) and add a remote server using the hosted URL; check its connection status and use the API-token route if your version does not complete OAuth. JetBrains' guide. For Zed, use context_servers with the hosted URL in its settings; omitting Authorization starts its OAuth flow. Zed's guide.

Local stdio server

Local mode needs an API token. Use it when your client only supports local processes or you want the MCP process on your machine; it still calls the AceDataCloud API and does not run Suno locally.

# Install once, then run the local stdio server
python -m pip install mcp-suno
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-suno

For Claude Desktop's local MCP configuration, merge this into the file opened by its developer settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS). This is a local uvx process; it is separate from the remote custom connector above:

{
  "mcpServers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Keep this user-level file private. On Windows, set $env:ACEDATACLOUD_API_TOKEN = 'YOUR_API_TOKEN' in the shell that starts local clients. uvx requires uv on PATH; mcp-suno requires the package installed in the environment from which the client launches it.

For self-hosted HTTP, run mcp-suno --transport http --port 8000 or build this repository's Dockerfile and run the resulting image. Clients must send their own Bearer tokens; expose the service only with suitable network and TLS controls.

Check the connection before generating

1. https://suno.mcp.acedata.cloud/health returning {"status":"ok"} checks reachability only, not authentication.
2. Use the client's MCP server list to confirm Suno tools appear. suno_list_models and suno_list_actions return static reference data; they confirm tool loading, not that your downstream API credential or balance works.
3. When ready, ask the client to call suno_generate_music with a short prompt. Save the returned task ID, then call suno_get_task until it completes. This is the first end-to-end API check and can be billed. Check the current Suno service limits and pricing before this step.

If you see 401, check whether the client completed OAuth or sent a valid token, and do not configure both paths at once. If OAuth redirects but fails, retry from the same client session; if the account cannot create or retrieve a credential, resolve that in AceDataCloud Platform. A tool list can load while an API call fails for balance, permissions, or service availability, so check the returned error rather than assuming the connection failed.

Use the tools

Tool names in the client include the suno_ prefix. Start with suno_list_models or suno_list_actions to confirm the connection. For generation, use suno_generate_music for a prompt or suno_generate_custom_music for your own lyrics and style. Advanced operations, media conversion, personas, and custom models are listed in the tool reference and exposed by the MCP server.

Generation and edits return a task ID, not a finished song. Query suno_get_task (or suno_get_tasks_batch for multiple IDs) until the task reports success and final media URLs. An intermediate audio URL may be only a preview; a failed task should stop polling. Do not repeat the generation call to check progress, because it may submit and bill another task.

Example request to your MCP client:

Use suno_generate_music to create a short upbeat acoustic birthday song. Give me the task ID, check it with suno_get_task, and share the final audio only after the task completes.

For custom lyrics:

Use suno_generate_custom_music with title “Storm”, style “energetic rock”, and these lyrics: [Verse] Thunder in the night [Chorus] We are the storm. Then follow the returned task ID to completion.

Available Models

Vocal Gender Control (v4.5+ only):

• f - Female vocals
• m - Male vocals

Configuration

Environment Variables

Command Line Options

mcp-suno --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

Development

Setup Development Environment

# Clone repository
git clone https://github.com/AceDataCloud/SunoMCP.git
cd SunoMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

Run Tests

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

Build & Publish

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

Project Structure

SunoMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for Suno API
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   ├── server.py          # MCP server initialization
│   └── utils.py           # Utility functions
├── tools/                  # MCP tool definitions
│   ├── __init__.py
│   ├── audio_tools.py     # Audio generation tools
│   ├── info_tools.py      # Information tools
│   ├── lyrics_tools.py    # Lyrics generation tools
│   ├── media_tools.py     # Media conversion tools
│   ├── persona_tools.py   # Persona management tools
│   ├── custom_model_tools.py # Custom music model tools
│   └── task_tools.py      # Task query tools
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_config.py
│   ├── test_integration.py
│   └── test_utils.py
├── deploy/                 # Deployment configs
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .env.example           # Environment template
├── .gitignore
├── CHANGELOG.md
├── Dockerfile             # Docker image for HTTP mode
├── docker-compose.yaml    # Docker Compose config
├── LICENSE
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
└── README.md

API Reference

This server wraps the AceDataCloud Suno API:

• Suno Audios API - Music generation
• Suno Lyrics API - Lyrics generation
• Suno Tasks API - Task queries
• Suno Persona API - Persona management

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

Documentation

Documentation

License

MIT License - see LICENSE for details.

Links

• AceDataCloud Platform
• Suno Official
• Model Context Protocol
• MCP Python SDK

Made with love by AceDataCloud