# Studio no Claude Desktop: o servidor MCP local > Faça o vídeo do Praeko Studio com um agente sem terminal (Claude Desktop, Cursor, Codex, Gemini CLI, opencode): instalação do `@praeko/studio-mcp`, as 14 ferramentas, o upload para o Praeko e a divisão com o MCP remoto que publica. Fonte: https://praeko.app/docs/studio/mcp Node 22 ou mais novo · stdio · Nunca publica · Remotion não é MIT O [Praeko Studio](https://praeko.app/docs/studio) normalmente é operado por um agente **com terminal**. O `@praeko/studio-mcp` é um servidor MCP que roda na **sua máquina** e expõe as mesmas etapas como ferramentas, para um agente **sem terminal** (o Claude Desktop, por exemplo) criar o episódio, escrever o roteiro, fazer a voz, renderizar, gerar a capa e subir o vídeo para o Praeko. Ele roda o CLI do Studio por baixo, por stdio: nenhuma porta é aberta. > **No ar no npm** O `@praeko/studio-mcp` (0.1.1, conferido em 08/11/2026) está publicado: os comandos abaixo funcionam como estão escritos. Ele não dispensa a máquina: precisa de Node, de Chrome/Remotion para renderizar e das suas chaves, tudo no seu computador. > **Guia de ponta a ponta** Para ir do zero à publicação com um agente, passo a passo, veja [Começar com o seu agente](https://praeko.app/docs/get-started-with-agent): ele cobre o caminho sem terminal (`studio_upload` e depois `create_post`) e o com terminal. ## Dois servidores, dois papéis | | `praeko` (remoto) | `praeko-studio` (local) | |---|---|---| | Onde roda | `https://praeko.app/mcp`, na nuvem do Praeko | Na sua máquina, por stdio (`npx -y @praeko/studio-mcp`) | | Faz | Canais, mídia, posts (criar, agendar, editar, cancelar), métricas, docs | Criar o episódio, roteiro, voz, compilar, render, capa, checagem, pacote e subir os arquivos | | Publica? | Sim, **sempre em duas etapas** (prévia e `confirm`) | **Nunca.** Não cria post, não agenda, não tem fila nem conta | | Sua chave | Login por OAuth ou chave que você põe no cliente | A chave do Praeko e a do ElevenLabs ficam na sua máquina (Chaveiro, arquivo de segredos ou variável); o agente **nunca** as vê | Os nomes não colidem: o cliente prefixa cada ferramenta com o nome do servidor. Os dois podem ficar ligados ao mesmo tempo. ## O fluxo sem terminal ### 1. Criar `studio_brief_read` e `studio_brief_write` (marca e regras), `studio_new_episode`, `studio_write_script`, `studio_voice` em `draft` (voz silenciosa e grátis), `studio_compile` e `studio_check`. ### 2. Renderizar `studio_voice` em `final` (gasta caracteres do ElevenLabs: prévia e código de confirmação), `studio_render`, `studio_cover` e `studio_package`. As etapas lentas viram tarefas: acompanhe com `studio_job`. ### 3. Subir `studio_upload` envia o vídeo (`out/.mp4`) e a capa (`out/-cover.png`) para a sua biblioteca de mídia no Praeko e devolve só os `mediaId`. Em duas etapas: a primeira chamada mostra os arquivos, os tamanhos e o destino e dá um `confirmation_code`; só a segunda, com `confirm`, envia. **Não cria post e não publica.** ### 4. Publicar (no servidor remoto) Com o servidor [`praeko` remoto](https://praeko.app/docs/mcp) ligado, o agente usa os `mediaId` em `create_post` (ou `schedule_post`): `media: { video: , cover: }`. Essa ferramenta tem a sua própria prévia e só publica com o seu "sim". ## Instalar Crie o projeto uma vez (`npx @praeko/studio init meu-canal`: o comando termina imprimindo as duas linhas de instalação deste servidor com a pasta certa). Depois aponte o servidor para a pasta do projeto, a que tem `brand.json`; use o caminho **absoluto**. **Claude Code (uma linha)** ```bash claude mcp add praeko-studio -- npx -y @praeko/studio-mcp --project ``` **JSON equivalente** ```json { "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } ``` ## Um bloco por cliente Os formatos abaixo foram conferidos nas páginas dos fabricantes em 08/11/2026; onde não deu para conferir, a página diz. ### Claude Code Um comando registra o servidor (o `--` separa as opções do Claude do comando do servidor). O padrão guarda só para você, neste projeto; `--scope user` vale para todos. **Terminal** ```bash claude mcp add praeko-studio -- npx -y @praeko/studio-mcp --project ``` **.mcp.json (alternativa, no Git)** ```json { "mcpServers": { "praeko-studio": { "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } } } ``` > **Fonte** Conferido em 08/11/2026 em `code.claude.com/docs/en/mcp`: sintaxe `claude mcp add [opções] -- [args...]`; uma entrada sem `type` no `.mcp.json` é lida como servidor stdio. ### Claude Desktop Em Configurações, aba Desenvolvedor (Developer), clique em Editar configuração (Edit Config). O arquivo é `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ou `~/.config/Claude/claude_desktop_config.json` (Linux). Cole o bloco, **feche o Claude Desktop por completo e abra de novo**. Use o caminho absoluto da pasta. **claude_desktop_config.json** ```json { "mcpServers": { "praeko-studio": { "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } } } ``` > **Fonte** Conferido em 08/11/2026 em `modelcontextprotocol.io/docs/develop/connect-local-servers` (a página usa o Claude Desktop como exemplo). Este é o caminho de servidor **local**; o conector personalizado de [Praeko remoto](https://praeko.app/docs/agents/claude-desktop) é outra coisa. ### Cursor No `.cursor/mcp.json` do projeto, ou em `~/.cursor/mcp.json` para todos. Servidor local pede `type: stdio`. **.cursor/mcp.json** ```json { "mcpServers": { "praeko-studio": { "type": "stdio", "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } } } ``` > **Fonte** Conferido em 08/11/2026 em `cursor.com/docs/context/mcp`. ### Codex Um comando (o `--` separa o comando do servidor) ou a tabela `[mcp_servers.]` no `~/.codex/config.toml` (ou `.codex/config.toml` de um projeto confiável). **Terminal** ```bash codex mcp add praeko-studio -- npx -y @praeko/studio-mcp --project ``` **~/.codex/config.toml** ```toml [mcp_servers.praeko-studio] command = "npx" args = ["-y","@praeko/studio-mcp","--project",""] ``` > **Fonte** Conferido em 08/11/2026 na documentação de MCP do Codex (OpenAI, `learn.chatgpt.com/docs/extend/mcp`). ### Gemini CLI No `.gemini/settings.json` do projeto, ou em `~/.gemini/settings.json` para todos. **settings.json** ```json { "mcpServers": { "praeko-studio": { "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } } } ``` > **Transição para o Antigravity CLI** Conferido em 08/11/2026 em `geminicli.com/docs/tools/mcp-server`, que avisa que o Gemini CLI foi substituído pelo Antigravity CLI em 18/06/2026 para contas gratuitas e Google One. O comando `gemini mcp add` existe, mas não o mostramos: as opções do Gemini e os argumentos do servidor (`-y`) podem se misturar. Para o Antigravity: confira na documentação do cliente. ### opencode No `opencode.json` (ou `opencode.jsonc`); o servidor local usa `type: local` e o comando inteiro como lista. **opencode.json** ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "servers": { "praeko-studio": { "type": "local", "command": [ "npx", "-y", "@praeko/studio-mcp", "--project", "" ] } } } } ``` > **Confira na documentação do cliente** A página do opencode de 08/11/2026 (`opencode.ai/docs/mcp-servers`) mostra os servidores dentro de `mcp.servers`; versões mais antigas usavam `mcp.` direto. Não deu para conferir o nome exato do arquivo nem a versão em que o formato mudou: confira na documentação do cliente, ou use `opencode mcp add`. ### Outro cliente (genérico) Qualquer cliente que rode servidor MCP local por stdio aceita o mesmo trio: comando, argumentos e (se precisar) variáveis de ambiente. Os nomes dos campos variam por cliente: confira na documentação do cliente. **Bloco JSON (o formato mais comum)** ```json { "mcpServers": { "praeko-studio": { "command": "npx", "args": [ "-y", "@praeko/studio-mcp", "--project", "" ] } } } ``` **Os três valores** ```text command: npx args: ["-y","@praeko/studio-mcp","--project",""] server: stdio (no port, no URL) ``` ## As 14 ferramentas | Ferramenta | O que faz | |---|---| | `studio_status` | Confere o ambiente (Node, ffmpeg, Chrome, fontes, contas de voz sem chaves, licença) e avisa se a chave do Praeko é admin. | | `studio_docs` | Lista ou devolve os tópicos de documentação do Studio. | | `studio_brief_read`, `studio_brief_write` | Lê e grava `brief.md`, `playbook.md` e `brand.json` (validado, com `.bak`). | | `studio_new_episode` | Cria `episodes//`. | | `studio_write_script` | Grava `script.txt` ou `episode.yaml` (o YAML é validado). | | `studio_voice` | `draft`: voz silenciosa, grátis. `final`: gasta caracteres do ElevenLabs e é em **duas etapas** (prévia com caracteres do roteiro, conta e saldo, aviso se o saldo não basta, e um `confirmation_code`). | | `studio_compile`, `studio_check` | Compila o `episode.yaml` e confere o episódio. | | `studio_render`, `studio_cover`, `studio_package` | Tarefas em segundo plano (`jobId`): vídeo, capa e textos de publicação. Num post de imagem (`studio_new_episode` com `format: image`), `studio_render` renderiza o slide em `out/-slide-01.jpg` (1080x1350, JPEG) e `studio_cover` é recusado. | | `studio_job` | Estado, log ou cancelamento de uma tarefa. Uma tarefa por vez por projeto. | | `studio_upload` | Sobe o vídeo e a capa do episódio (ou, num post de imagem, o JPEG como `type: image`) para a biblioteca de mídia do Praeko, em **duas etapas**, e devolve só os `mediaId`. Não cria post. | > **Uma chave write, não admin** O `studio_upload` usa a sua chave do Praeko (`PRAEKO_KEY`, o Chaveiro do macOS ou o arquivo de segredos, como o resto do Studio). Ele só precisa enviar arquivos: crie em Chaves de API uma chave de escopo **`write`** para o Studio. Se a chave achada for `admin`, o `studio_status` e o `praeko studio doctor` mostram um aviso (não um erro). O endereço do serviço não vem do `brand.json`, para que um texto escrito pelo agente nunca desvie a chave. ## Segurança | Garantia | Como | |---|---| | Só stdio | Nenhuma porta aberta, nada acessível pela rede. | | Sem comando livre | As ferramentas chamam o CLI do Studio com argumentos fixos; o que o agente escreve nunca vira linha de comando. Nomes de episódio seguem `^[a-z0-9][a-z0-9-]*$` e todo caminho fica dentro do projeto. | | Chaves | Nenhuma resposta, log ou erro mostra uma chave: os valores são mascarados (`sk_…3e`). | | Texto do projeto é dado | `script.txt`, `brief.md` e a saída do CLI voltam marcados como `untrusted`: o servidor não obedece ao que estiver escrito neles. | | Gasto só com o seu sim | `studio_voice` final e `studio_upload` são em duas etapas: o código é curto, ligado aos argumentos (e aos arquivos), vale 10 minutos e funciona uma vez. | | Recursos | Uma tarefa por vez por projeto, tempo máximo por tarefa, cancelamento. Sem telemetria. | > **Licença do Remotion** O pacote é MIT, mas o **Remotion** (motor padrão de vídeo e capa) **não** é: grátis para pessoas, organizações sem fins lucrativos e empresas de até 3 funcionários; empresas maiores precisam da licença de empresa ([remotion.pro/license](https://www.remotion.pro/license)). A licença é de quem instala e roda. Detalhes em [Praeko Studio](https://praeko.app/docs/studio). ## Se der errado | Sintoma | Causa provável | O que fazer | |---|---|---| | O servidor não aparece no cliente | O cliente não foi reiniciado, ou o JSON tem erro. | Reinicie o cliente por completo, confira o JSON e rode o comando à mão no terminal. | | `has no brand.json` | `--project` não aponta para a pasta do projeto. | Use o caminho absoluto da pasta com `brand.json` e `src/index.ts`. | | `no Praeko key found` | O `studio_upload` não achou a chave. | Guarde uma chave `write` (`PRAEKO_KEY` no ambiente do servidor, ou `praeko studio schedule --via praeko --key` num terminal). Nunca cole a chave no chat. | | `reason: expired`, `unknown_code` ou `arguments_changed` | Passaram 10 minutos, o código já foi usado, o servidor reiniciou, ou o arquivo/roteiro mudou depois da prévia. | Peça uma prévia nova e confirme sem mexer em nada. | | `INSUFFICIENT BALANCE` na prévia da voz | Nenhuma conta com chave tem caracteres para o roteiro. | Adicione crédito ou outra conta (`praeko studio voice account add`) e peça a prévia de novo. |