> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de Integração do Suno MCP

> suno MCP 服务器集成

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) é um protocolo de contexto de modelo lançado pela Anthropic, que permite que modelos de IA (como Claude, GPT, etc.) chamem ferramentas externas através de interfaces padronizadas. Com o Suno MCP Server fornecido pela XHuoAPI, você pode gerar música, letras e gerenciar projetos de áudio diretamente em clientes de IA como Claude Desktop, VS Code, Cursor, entre outros.

## Visão Geral das Funcionalidades

O Suno MCP Server oferece as seguintes funcionalidades principais:

* **Geração de Música** — Geração de música AI através de prompts de texto
* **Criação Personalizada** — Controle total sobre letras, títulos e estilos musicais
* **Continuação de Canções** — Prolongar canções existentes a partir de qualquer ponto no tempo
* **Covers/Mixagens** — Criar versões cover em diferentes estilos
* **Geração de Letras** — Gerar letras estruturadas com base em descrições
* **Personagens Vocais** — Salvar e reutilizar estilos de voz
* **Conversão de Mídia** — Obter MP4, WAV, MIDI, separação de vozes, etc.
* **Otimização de Estilo** — Otimizar etiquetas de estilo musical
* **Consulta de Tarefas** — Monitorar o progresso da geração e obter resultados

## Preparativos

Antes de usar, você precisa obter o Token da API da XHuoAPI:

1. Registre-se ou faça login na [plataforma XHuoAPI](https://api.xhuoapi.ai)
2. Vá para a página [Suno Audios API](https://api.xhuoapi.ai/documents/suno-audios)
3. Clique em "Acquire" para obter o Token da API (primeira solicitação oferece crédito gratuito)

## Instalação e Configuração

### Método 1: Instalação via pip (recomendado)

```bash theme={null}
pip install mcp-suno
```

### Método 2: Instalação a partir do código-fonte

```bash theme={null}
git clone https://github.com/XHuoAPI/SunoMCP.git
cd SunoMCP
pip install -e .
```

Após a instalação, você pode usar o comando `mcp-suno` para iniciar o serviço.

## Usando no Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Adicione a seguinte configuração:

```json theme={null}
{
  "mcpServers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "XHuoAPI_API_TOKEN": "seu Token da API"
      }
    }
  }
}
```

Se usar `uvx` (sem necessidade de instalar pacotes previamente):

```json theme={null}
{
  "mcpServers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "XHuoAPI_API_TOKEN": "seu Token da API"
      }
    }
  }
}
```

Após salvar a configuração, reinicie o Claude Desktop para usar as ferramentas relacionadas ao Suno nas conversas.

## Usando no VS Code / Cursor

Crie um arquivo `.vscode/mcp.json` no diretório raiz do projeto:

```json theme={null}
{
  "servers": {
    "suno": {
      "command": "mcp-suno",
      "env": {
        "XHuoAPI_API_TOKEN": "seu Token da API"
      }
    }
  }
}
```

Ou use `uvx`:

```json theme={null}
{
  "servers": {
    "suno": {
      "command": "uvx",
      "args": ["mcp-suno"],
      "env": {
        "XHuoAPI_API_TOKEN": "seu Token da API"
      }
    }
  }
}
```

## Lista de Ferramentas Disponíveis

| Nome da Ferramenta           | Descrição                                               |
| ---------------------------- | ------------------------------------------------------- |
| `suno_generate_music`        | Geração de música através de prompts de texto           |
| `suno_generate_custom_music` | Geração de música com letras e estilos personalizados   |
| `suno_extend_music`          | Continuação de canções a partir de um ponto específico  |
| `suno_cover_music`           | Criação de versões cover                                |
| `suno_concat_music`          | Junção de trechos de canções                            |
| `suno_generate_with_persona` | Geração de música usando um personagem vocal específico |
| `suno_remaster_music`        | Remasterização de áudio                                 |
| `suno_stems_music`           | Separação de faixas (vocal/acompanhamento)              |
| `suno_replace_section`       | Substituição de trechos específicos em canções          |
| `suno_upload_extend`         | Upload de áudio e continuação                           |
| `suno_upload_cover`          | Upload de áudio e criação de cover                      |
| `suno_mashup_music`          | Mistura de várias canções                               |
| `suno_generate_lyrics`       | Geração de letras com base em descrições                |
| `suno_create_persona`        | Criação de personagem vocal                             |
| `suno_get_mp4`               | Obtenção de vídeo MP4 da canção                         |
| `suno_get_timing`            | Obtenção da linha do tempo das letras                   |
| `suno_extract_vocals`        | Extração de vocais                                      |
| `suno_get_wav`               | Obtenção de WAV de alta qualidade                       |
| `suno_get_midi`              | Obtenção de arquivo MIDI                                |
| `suno_optimize_style`        | Otimização de etiquetas de estilo musical               |
| `suno_mashup_lyrics`         | Mistura de letras                                       |
| `suno_upload_audio`          | Upload de áudio personalizado                           |
| `suno_get_task`              | Consulta de status de uma única tarefa                  |
| `suno_get_tasks_batch`       | Consulta em lote de status de tarefas                   |

## Exemplos de Uso

Após a configuração, você pode chamar essas funcionalidades diretamente em linguagem natural nos clientes de IA, por exemplo:

* "Ajude-me a gerar uma música pop sobre o verão"
* "Faça um cover desta música em estilo jazz"
* "Continue esta música a partir dos 30 segundos"
* "Gere uma letra em chinês com o tema de viagem"
* "Separe a voz desta música"
* "Ajude-me a converter esta música para o formato MIDI"

## Mais Informações

* Repositório no GitHub: [XHuoAPI/SunoMCP](https://github.com/XHuoAPI/SunoMCP)
* Pacote PyPI: [mcp-suno](https://pypi.org/project/mcp-suno/)
* Documentação da API: [API de Geração de Música Suno](https://api.xhuoapi.ai/documents/suno)