@justmpm/minimax-video-understand

v0.1.0

Published

9 days ago

MCP Server for video understanding using MiniMax M3 multimodal model

0High
0Medium
0Low

justmpm

mcp minimax m3 video video-understanding multimodal ai token-plan

@justmpm/minimax-video-understand

MCP Server para análise e compreensão de vídeos usando o modelo MiniMax M3 (multimodal nativo).

Descrição

Este servidor MCP (Model Context Protocol) permite que IAs assistam e entendam o conteúdo de vídeos. O modelo MiniMax M3 analisa os vídeos e responde perguntas sobre eles — incluindo comparações entre múltiplos vídeos.

Casos de uso:

Resumir o conteúdo de um vídeo (aula, palestra, tutorial, filme, etc)
Comparar dois ou mais vídeos e descrever diferenças
Identificar pessoas, objetos, ações, cenários
Responder perguntas específicas sobre o que acontece no vídeo
Analisar vídeos longos com controle de FPS para economizar tokens

Por que usar?

Modelo nativo multimodal: O M3 foi treinado com vídeo desde o passo 0 (não é um modelo de visão adaptado)
Contexto gigante: 1M de tokens (MSA architecture) — suporta vídeos longos
Múltiplos vídeos: Pode analisar e comparar vários vídeos no mesmo request
Integração MCP: Funciona com Claude Desktop, OpenCode, Cursor, etc
Fácil configuração: Basta uma Token Plan subscription key da MiniMax

Instalação

Você tem 3 opções de instalação. Escolha a que melhor se adequa ao seu fluxo:

Opção 1: Via npx (sem instalar nada)

Útil para experimentar rápido ou para uso pontual. O npx baixa o pacote temporariamente:

npx -y @justmpm/minimax-video-understand

Opção 2: Instalação global (recomendado para uso frequente)

Instala o binário minimax-video-understand no PATH do sistema, disponível em qualquer terminal:

npm install -g @justmpm/minimax-video-understand

Depois você pode rodar diretamente:

minimax-video-understand --version
minimax-video-understand --help

Vantagem: inicialização mais rápida (sem download a cada execução) e você pode usar o binário em qualquer lugar do sistema.

Opção 3: Desenvolvimento local (se você clonou o repo)

Para quem vai modificar o código ou contribuir:

git clone https://github.com/justmpm/minimax-video-understand-mcp
cd minimax-video-understand
npm install
npm run build

Configuração

1. Obter a Subscription Key

Acesse MiniMax Token Plan
Assine o Token Plan (você já é assinante!)
Copie sua Subscription Key em Billing > Token Plan

2. Configurar a Subscription Key (3 formas)

Você tem 3 formas de fornecer a MINIMAX_API_KEY. Escolha a que preferir:

Forma 1 — Arquivo `.env` (recomendado) ✅

Crie um arquivo .env (caminho padrão: raiz do projeto MCP).

No projeto onde você roda OpenCode (C:\Users\tetu_\.config\opencode\.env por exemplo):

MINIMAX_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.sua-chave-aqui
MINIMAX_LOG_LEVEL=info

Ou na raiz do próprio MCP (mcps-ai/minimax-video-understand/.env):

MINIMAX_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.sua-chave-aqui

Para apontar para um .env em qualquer outro lugar, defina MINIMAX_ENV_FILE no opencode.json:

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["minimax-video-understand"],
      "env": {
        "MINIMAX_ENV_FILE": "C:/Users/tetu_/.config/opencode/.env"
      }
    }
  }
}

Vantagens: chave fora do config, versionável com .gitignore, suporta outras envs (LOG_LEVEL, etc).

Forma 2 — Variável de ambiente do sistema

Defina MINIMAX_API_KEY no seu sistema operacional. O MCP herda automaticamente.

Windows (PowerShell):

[System.Environment]::SetEnvironmentVariable('MINIMAX_API_KEY', 'sua-chave', 'User')

Windows (CMD):

setx MINIMAX_API_KEY "sua-chave"

Linux/Mac:

export MINIMAX_API_KEY="sua-chave"   # adicione ao ~/.bashrc ou ~/.zshrc

Depois reinicie o OpenCode/Claude Desktop para herdar a nova env.

Vantagens: chave nunca toca arquivos, funciona em qualquer projeto.

Forma 3 — Hardcoded na config do MCP (NÃO recomendado ⚠️)

Edite o opencode.json ou claude_desktop_config.json:

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["minimax-video-understand"],
      "env": {
        "MINIMAX_API_KEY": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.sua-chave-aqui"
      }
    }
  }
}

⚠️ Problema: a chave vai pro git se você versionar o config. Use apenas para testes rápidos.

3. Configurar no OpenCode

Adicione ao seu arquivo opencode.json (geralmente em ~/.config/opencode/):

Opção A — Via npx (sem instalar):

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["npx", "-y", "@justmpm/minimax-video-understand"]
    }
  }
}

(usa .env ou env do sistema para a key)

Opção B — Binário global (mais rápido, requer npm install -g):

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["minimax-video-understand"]
    }
  }
}

Opção C — Caminho local (para desenvolvimento):

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["node", "D:/caminho/para/minimax-video-understand/dist/index.js"]
    }
  }
}

Se quiser usar um .env em outro lugar (ex: ~/.config/opencode/.env), adicione MINIMAX_ENV_FILE:

{
  "mcp": {
    "minimax-video-understand": {
      "type": "local",
      "command": ["minimax-video-understand"],
      "env": {
        "MINIMAX_ENV_FILE": "C:/Users/tetu_/.config/opencode/.env"
      }
    }
  }
}

4. Configurar no Claude Desktop

Adicione ao seu claude_desktop_config.json:

Opção A — Via npx:

{
  "mcpServers": {
    "minimax-video-understand": {
      "command": "npx",
      "args": ["-y", "@justmpm/minimax-video-understand"]
    }
  }
}

Opção B — Binário global:

{
  "mcpServers": {
    "minimax-video-understand": {
      "command": "minimax-video-understand"
    }
  }
}

Com .env customizado (qualquer uma das opções acima + env):

{
  "mcpServers": {
    "minimax-video-understand": {
      "command": "minimax-video-understand",
      "env": {
        "MINIMAX_ENV_FILE": "C:/Users/tetu_/claude/.env"
      }
    }
  }
}

Uso

Uma vez configurado, basta conversar naturalmente com a IA. Ela detectará quando usar a tool analyze_video.

Exemplo 1: Analisar um vídeo

Você: D:/videos/aula-typescript.mp4 sobre o que é esse vídeo?

IA: [usa analyze_video internamente]

Resposta do M3: "Esta é uma aula introdutória sobre TypeScript. O instrutor 
explica os conceitos básicos de tipos estáticos, interfaces, generics, e 
demonstra exemplos práticos de código..."

Exemplo 2: Comparar dois vídeos

Você: D:/v1.mp4 e D:/v2.mp4 qual a diferença entre esses 2 vídeos?

IA: [usa analyze_video com 2 paths]

Resposta do M3: "O vídeo 1 mostra um gato laranja brincando com um novelo 
de lã, enquanto o vídeo 2 mostra um cachorro labrador correndo em um parque. 
Ambos os vídeos foram gravados ao ar livre durante o dia..."

Exemplo 3: Análise detalhada

Você: Analise detalhadamente D:/entrevista.mp4 e me diga quem aparece e o que discutem

IA: [usa analyze_video com detail="high"]

Resposta do M3: "Nesta entrevista aparecem 3 pessoas: João (entrevistador, 
homem de barba, camiseta azul), Maria (entrevista, mulher de cabelo cacheado, 
óculos) e Pedro (co-apresentador, homem de terno). O tópico principal da 
discussão é..."

Tools Disponíveis

`analyze_video` - Analisa vídeos

Analisa um ou mais vídeos usando MiniMax M3 e responde perguntas sobre o conteúdo.

Parâmetros:

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | videoPaths | string[] | Sim | Array com 1+ caminhos absolutos de vídeos. Suporta MP4, AVI, MOV, MKV. | | question | string | Não | Pergunta sobre o(s) vídeo(s). Default: "Descreva o que acontece..." | | detail | "low" \| "default" \| "high" | Não | Nível de detalhe (default: "default") | | fps | number (0.2-5) | Não | Frames por segundo (default: 1) |

Retorno:

✅ Análise concluída!

📹 Vídeos analisados: 1
📦 Tamanho total: 12.45 MB
🤖 Modelo: MiniMax-M3

💬 Pergunta: Sobre o que é esse vídeo?

━━━ Resposta do MiniMax M3 ━━━

[resposta do modelo]

Formatos Suportados

| Formato | Extensão | Limite | |---------|----------|--------| | MP4 | .mp4 | 512MB | | AVI | .avi | 512MB | | MOV | .mov | 512MB | | MKV | .mkv | 512MB | | WEBM | .webm | 512MB |

Limites:

Inline (base64): até 50MB
Upload via Files API: 50MB a 512MB
Acima de 512MB: erro amigável retornado antes de tentar processar

Níveis de Detalhe

| Nível | Quando usar | Custo (tokens) | |-------|-------------|----------------| | low | Overview rápido, vídeos longos onde só precisa de um resumo | Baixo | | default | Maioria dos casos (recomendado) | Médio | | high | Análise detalhada, rostos, textos pequenos, ações específicas | Alto |

Configuração de FPS

| FPS | Quando usar | |-----|-------------| | 0.2-0.5 | Vídeos estáticos (entrevistas, palestras) — economia de tokens | | 1.0 (default) | Maioria dos vídeos | | 2.0-5.0 | Ações rápidas (esportes, dança, tutoriais com cortes) |

Exemplos Avançados

Resumir uma aula longa

{
  "videoPaths": ["D:/cursos/aula-completa.mp4"],
  "question": "Resuma esta aula em 5 tópicos principais com timestamps",
  "detail": "high"
}

Comparar versões de um vídeo

{
  "videoPaths": ["D:/videos/v1-original.mp4", "D:/videos/v2-editado.mp4"],
  "question": "Quais são as diferenças entre essas duas versões?",
  "detail": "default"
}

Análise rápida de múltiplos clipes

{
  "videoPaths": [
    "D:/clips/clip1.mp4",
    "D:/clips/clip2.mp4",
    "D:/clips/clip3.mp4"
  ],
  "question": "O que acontece em cada um desses clipes?",
  "detail": "low",
  "fps": 0.5
}

Estrutura do Projeto

minimax-video-understand/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── client.ts             # Cliente MiniMax (upload + chat)
│   ├── types.ts              # Tipos TypeScript
│   └── tools/
│       ├── index.ts          # Barrel export
│       └── analyze-video.ts  # Tool analyze_video
├── dist/                     # Build compilado
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── README.md                 # Este arquivo
├── CLAUDE.md                 # Documentação técnica para IAs
└── AGENTS.md                 # Guia para subagents

Desenvolvimento

# Clonar repositório
git clone https://github.com/justmpm/minimax-video-understand-mcp

# Instalar dependências
npm install

# Build
npm run build

# Desenvolvimento com watch
npm run dev

# Testes
npm test

# Executar
MINIMAX_API_KEY=sua-key npm start

# Testar como se fosse global (sem publicar)
npm link
# Agora `minimax-video-understand` está disponível no PATH
# Use Opção B das configurações acima

Limitações Conhecidas

Tamanho do vídeo: Máximo 512MB (limite da API)
Request body: Máximo 64MB para inline
Vídeo expira: 7 dias após upload via Files API
Rate limits: Sujeito aos limites do Token Plan
Formatos: Apenas MP4, AVI, MOV, MKV

Troubleshooting

"MINIMAX_API_KEY não definida"

Você tem 3 opções para configurar a chave (escolha uma):

1. Crie um arquivo .env (recomendado):

# Na raiz do projeto MCP ou em outro lugar
echo "MINIMAX_API_KEY=sua-chave" > .env

# Ou aponte para um .env em outro lugar via MINIMAX_ENV_FILE

2. Defina como variável de ambiente do sistema:

# Linux/Mac
export MINIMAX_API_KEY="sua-chave"

# Windows PowerShell
[System.Environment]::SetEnvironmentVariable('MINIMAX_API_KEY', 'sua-chave', 'User')

3. Hardcoded na config do MCP (não recomendado, mas funciona):

{ "env": { "MINIMAX_API_KEY": "sua-chave" } }

O MCP mostra uma mensagem de erro amigável listando as 3 opções quando a key não é encontrada.

"Arquivo .env não está sendo carregado"

Verifique se o arquivo se chama exatamente .env (sem extensão tipo .env.txt)
Se o .env está em outro lugar, defina MINIMAX_ENV_FILE no MCP config com o path absoluto
O MCP loga 📄 .env carregado de: <path> no stderr quando carrega com sucesso — confira os logs
O MCP avisa ⚠️ MINIMAX_ENV_FILE definido mas arquivo não encontrado: <path> se o path for inválido

"Video file not found"

Verifique se o caminho está correto e se o arquivo existe. Use caminhos absolutos.

"Upload failed (401)"

Sua subscription key pode estar inválida ou expirada. Renove em Billing > Token Plan.

"Upload failed (413)"

O vídeo excede 512MB. Comprima ou divida o vídeo antes de analisar.

Resposta vazia ou genérica

Tente aumentar detail para "high" ou ajustar fps para capturar mais frames.

Documentação Adicional

CLAUDE.md

Documentação técnica para IAs sobre como o MCP funciona internamente. Inclui:

Arquitetura do sistema
Fluxo de dados
Decisões de design
Como estender com novas tools

Para IAs: Leia CLAUDE.md para entender a arquitetura e implementação.

AGENTS.md

Guia simplificado para subagents sobre como usar a tool. Inclui:

Referência rápida da tool
Exemplos de uso
Dicas de troubleshooting

Para Subagents: Consulte AGENTS.md para orientações rápidas.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@justmpm/minimax-video-understand

Descrição

Por que usar?

Instalação

Opção 1: Via npx (sem instalar nada)

Opção 2: Instalação global (recomendado para uso frequente)

Opção 3: Desenvolvimento local (se você clonou o repo)

Configuração

1. Obter a Subscription Key

2. Configurar a Subscription Key (3 formas)

Forma 1 — Arquivo .env (recomendado) ✅

Forma 2 — Variável de ambiente do sistema

Forma 3 — Hardcoded na config do MCP (NÃO recomendado ⚠️)

3. Configurar no OpenCode

4. Configurar no Claude Desktop

Uso

Exemplo 1: Analisar um vídeo

Exemplo 2: Comparar dois vídeos

Exemplo 3: Análise detalhada

Tools Disponíveis

analyze_video - Analisa vídeos

Formatos Suportados

Níveis de Detalhe

Configuração de FPS

Exemplos Avançados

Resumir uma aula longa

Comparar versões de um vídeo

Análise rápida de múltiplos clipes

Estrutura do Projeto

Desenvolvimento

Limitações Conhecidas

Troubleshooting

"MINIMAX_API_KEY não definida"

"Arquivo .env não está sendo carregado"

"Video file not found"

"Upload failed (401)"

"Upload failed (413)"

Resposta vazia ou genérica

Documentação Adicional

CLAUDE.md

AGENTS.md

Links

Licença

Forma 1 — Arquivo `.env` (recomendado) ✅

`analyze_video` - Analisa vídeos