Suno-MCP: Cloudflare Worker + Containerized Browser Service (Monorepo)

Overview

This monorepo contains the Suno MCP server project, which adapts gcui-art/suno-api to create a suno-mcp server that allows music generation to be done collaboratively with an LLM. Songs will be generated in the user's Suno account.

Important Note

This project is not intended to bypass or circumvent Suno's terms and conditions in any way. Rather, it is designed as a tool to enhance your AI music generation workflow.

The typical workflow for using generative AI with Suno AI usually involves:

1. Asking an AI chat tool to help generate prompts and lyrics
2. Checking and formatting the output
3. Copying the content to your clipboard
4. Manually pasting it into suno.com

This process is unnecessarily tedious. This MCP server is meant to ease that pain by allowing AI assistants to directly interact with Suno, streamlining the creative process.

Please be aware:

• This is an unofficial project that is not endorsed by Suno
• It is not based on an official API
• The project is subject to break at any point when Suno updates their application
• Users should be prepared to adapt to changes or wait for updates when Suno makes breaking changes

Monorepo Structure

This project uses pnpm workspaces with the following structure:

/
  apps/
    suno-mcp/          # Cloudflare Worker MCP Server
    suno-api/          # Suno API stub (actual implementation in separate repo)
  packages/
    suno-contracts/    # Shared zod-openapi schemas

Packages

• apps/suno-mcp: The Cloudflare Worker acting as the MCP Server (Agent). It exposes MCP tools that correspond to endpoints in the Suno API.
• apps/suno-api: A placeholder for the Node.js service (Docker container) running Playwright. The actual implementation is in a separate repository.
• packages/suno-contracts: Shared zod-openapi schemas used for:
  • Validation
  • OpenAPI metadata
  • Type inference via z.infer

Development

# Install dependencies
pnpm install

# Run MCP server in development mode
pnpm dev:mcp

# Run API server in development mode (stub)
pnpm dev:api

# Build all packages
pnpm build

# Deploy MCP server
pnpm deploy:mcp

Using the MCP Server

Remote Instance

A remote instance of this MCP server is available at:

https://suno-mcp.xvzf.workers.dev/

You can connect to it using the MCP Inspector with the following settings:

• Transport Type: SSE
• URL: https://suno-mcp.xvzf.workers.dev/sse
• Connection Type: Direct

After connecting, you'll need to authenticate with Google and set your Suno cookie (see steps below).

Local Development & Testing

Using the MCP Inspector

You can test the MCP server locally using the MCP Inspector tool. The same authentication and setup steps apply whether you're using the remote instance or running locally. Here's how to run it locally:

Step 1: Start the MCP Server

From the top-level of the project, run:

pnpm run dev:mcp

This will start the MCP server on http://localhost:8787.

Step 2: Start the MCP Inspector

In a separate terminal, run:

npx @modelcontextprotocol/inspector@latest

This will open the MCP Inspector in your browser.

Step 3: Connect to the Local Server

In the MCP Inspector:

1. Set the Transport Type to SSE
2. Enter the URL: http://localhost:8787/sse
3. Set the Connection Type to Direct
4. Click the Connect button

Step 4: Authenticate with Google

After connecting, you'll be redirected to authenticate with your Google account. Complete the OAuth flow to proceed.

Step 5: Set Your Suno Cookie

Once authenticated, you need to set your Suno session cookie:

1. Open your browser's Developer Tools (F12)
2. Navigate to the Network tab
3. Go to suno.com and log in
4. Find a network request that contains clerk_api in the URL
5. Copy the Cookie value from the request headers
6. In the MCP Inspector, use the suno_set_cookie tool and paste the cookie value

Step 6: Refresh to See All Tools

After setting the cookie, refresh the MCP Inspector (or reconnect). All MCP tools will now be available for use.

Testing

This project uses Vitest for unit and E2E testing with comprehensive test coverage.

# Run all unit tests
pnpm test

# Run tests for specific apps
pnpm test:api      # Run suno-api unit tests
pnpm test:mcp      # Run suno-mcp unit tests

# Run E2E tests
pnpm test:e2e:api  # Run suno-api E2E tests

# Run tests with coverage
cd apps/suno-api && pnpm test:coverage
cd apps/suno-mcp && pnpm test:coverage

# Run tests in watch mode (for development)
cd apps/suno-api && pnpm test:watch

Test Structure:

• Unit tests are located in __tests__/ directories next to the code being tested
• Test files follow the naming convention: *.test.ts
• E2E tests are in dedicated tests/ directories at the app level
• All tests mock external dependencies for isolation
• CI/CD runs all tests on PRs to the main branch

See .cursorrules/testing.md for detailed testing conventions and best practices.

Architecture

This project implements the Suno MCP server using a distributed architecture optimized for Cloudflare:

1. apps/suno-mcp: A Cloudflare Worker acting as the MCP Server (Agent). It exposes MCP tools that correspond to each endpoint in the Node.js Suno API running inside containerized service via Service Bindings.
2. apps/suno-api: A Node.js service (Docker container) running Playwright. It manages browser sessions, handles automation, and exposes a REST API with Swagger UI documentation for interacting with suno's api. (Actual implementation in separate repository)
3. packages/suno-contracts: Shared zod-openapi schemas that ensure type safety across both applications.

How It Works

Container Lifecycle

When the MCPAgent durable object is created, it automatically creates an instance of the container. The container runs a lightweight Node.js HTTP API server that:

• Calls Suno APIs directly
• Uses Playwright to bypass captcha challenges
• Exposes all endpoints via REST API
• Provides Swagger UI documentation at http://localhost:8080/swagger-ui

Authentication Flow

1. Create Session: Users must first provide their Suno cookie to the suno_set_session MCP tool (or call POST /api/session directly).
2. Use Container: Once authenticated, the container can be used as a standard HTTP API. All subsequent requests will use the authenticated session.
3. Token Persistence: The Suno token is persisted in the container until either:
   • You overwrite it by setting a different token via suno_set_session
   • The token expires (at which point you'll need to re-authenticate)

Planned Features

• Google Authentication: A planned feature will allow authenticating with Google OAuth, providing a more seamless authentication experience without requiring manual cookie extraction.
• Rich Generate Parameters: Plans are in place to expand the generate endpoints with more comprehensive parameters, allowing for finer control over music generation including advanced style controls, tempo settings, key signatures, and more detailed production parameters.
• Persona Management: Full CRUD operations for personas are planned, including:
  • Getting persona information (currently available)
  • Creating new personas
  • Deleting personas
  • Updating persona settings

MCP Tools

The suno-mcp worker exposes an MCP tool for every endpoint in the Node.js Suno API. Each tool maps directly to a corresponding HTTP endpoint in the containerized service.

API Endpoints

The containerized service exposes the following REST API endpoints:

Method	Endpoint	Description
POST	/api/session	Set or update session cookie for authentication with Suno API. The cookie should be obtained from suno.com after logging in.
POST	/api/v1/generate	Generate audio based on prompt. Automatically fills in lyrics. Generates 2 audio files per request (consumes 10 credits). Supports wait_audio parameter for synchronous mode.
POST	/api/v1/custom_generate	Generate audio in custom mode with additional details like genre, lyrics, title, etc. Supports tags, negative_tags, and other customization options.
POST	/api/v1/generate_lyrics	Generate lyrics based on a prompt.
GET	/api/v1/get	Get audio information by IDs (comma-separated) or retrieve a list of all music. Supports pagination via page parameter.
GET	/api/v1/get_limit	Get quota information including remaining credits and usage statistics.
POST	/api/v1/extend_audio	Extend audio length by generating additional content. Supports continuation point, tags, and other parameters.
POST	/api/v1/generate_stems	Generate stem tracks to separate audio and music tracks.
GET	/api/v1/get_aligned_lyrics	Get lyric alignment (timestamps for each word) for a song. Requires song_id query parameter.
GET	/api/v1/clip	Get clip information based on ID. Requires id query parameter.
POST	/api/v1/concat	Generate the whole song from extensions by concatenating audio clips. Requires clip_id in request body.
GET	/api/v1/persona	Get persona information and associated clips. Requires id query parameter. Supports pagination via page parameter.
POST	/api/v1/chat/completions	Generate audio based on prompt in OpenAI API format compatibility. Converts the generate API to be compatible with OpenAI /v1/chat/completions format.

Swagger UI

The API documentation is available via Swagger UI at:

http://localhost:8080/swagger-ui

When running locally, you can access the interactive API documentation to explore all endpoints, request/response schemas, and test the API directly.

Prerequisites

1. Docker: To build the browser service container.
2. Cloudflare Wrangler: To deploy the worker and container.
3. Playwright: To generate the initial auth file locally (optional).

Setup

1. Browser Service (Container)

This service runs the actual browser automation and exposes a REST API to manage sessions.

Deploy to Cloudflare: (Follow standard Cloudflare Container deployment steps, e.g., via Workers with Containers or separate deployment bonded to the worker)

Ensure the service is named suno-browser-service so the Worker can bind to it.

Local Testing:

cd container_src
npm install
npm run dev

The service will start on http://localhost:8080 with Swagger UI available at http://localhost:8080/swagger-ui.

2. Cloudflare Worker (MCP Server)

The worker acts as the interface for MCP clients. It binds to the browser service.

Deploy:

npm install
npm run deploy

Ensure wrangler.jsonc has the correct binding:

"services": [
  { "binding": "BROWSER_SERVICE", "service": "suno-browser-service" }
]

3. Usage Workflow

Step 1: Authenticate Session Use your MCP client to set the Suno cookie:

Tool: suno_set_session Arguments: { "cookie": "<your-suno-cookie>" }

Alternatively, call the HTTP endpoint directly:

curl -X POST http://localhost:8080/api/session \
  -H "Content-Type: application/json" \
  -d '{"cookie": "<your-suno-cookie>"}'

Step 2: Use MCP Tools All subsequent tool calls will use the authenticated session. Available tools include:

• suno_generate - Generate audio based on prompt
• suno_custom_generate - Generate audio with custom parameters
• suno_generate_lyrics - Generate lyrics
• suno_get - Get audio information
• suno_get_limit - Get quota information
• suno_extend_audio - Extend audio length
• suno_generate_stems - Generate stem tracks
• suno_get_aligned_lyrics - Get lyric alignment
• suno_get_clip - Get clip information
• suno_concat - Concatenate clips into full song
• suno_get_persona - Get persona information
• suno_chat_completions - Generate audio (OpenAI format)
• suno_set_session - Set session cookie

API Reference (Worker)

• GET /tools: List available tools.
• POST /execute: Execute a tool. Body: { "name": "...", "arguments": { ... } }.

API Reference (Container Service)

All endpoints are documented in Swagger UI at http://localhost:8080/swagger-ui. The service exposes REST endpoints under /api/v1/* and /api/session.

License

See LICENSE file for details.

Reference Projects

• Suno API: github.com/gcui-art/suno-api
• Suno.ai official website: suno.ai