From financeiro
Skill de FALLBACK pra configurar o MCP server do FIN App. A partir da v0.2.0, o plugin já declara o fin-app-mcp via .mcp.json e pede a API key automaticamente no install (userConfig sensitive). Essa skill só roda se o método automático falhar OU se a pessoa precisar atualizar/revogar a chave manualmente. Guia: gerar API key, editar config (Desktop) ou rodar claude mcp add (Code), troubleshooting de erros comuns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/financeiro:instalar-fin-mcp (sem argumentos)(sem argumentos)This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
A partir da versão 0.2.0, o plugin **já declara** o `fin-app-mcp` via dois arquivos:
A partir da versão 0.2.0, o plugin já declara o fin-app-mcp via dois arquivos:
.mcp.json na raiz do plugin: declara fin-app com command: npx, args: ["-y", "fin-app-mcp"], e env vars FIN_BASE_URL (fixa) + FIN_API_KEY (referenciando ${user_config.fin_api_key})userConfig.fin_api_key no plugin.json com sensitive: trueResultado: quando a pessoa instala o plugin via /plugin install, o Claude pede a API key na hora, ela cola, e pronto. O MCP fin-app é registrado automaticamente. Sem editar claude_desktop_config.json. Sem claude mcp add.
Esta skill (/financeiro:instalar-fin-mcp) só é necessária se:
mcpServers inline foi corrigido com .mcp.json separado, mas pode haver outros)fin_listar_contas, deu erro, e suspeita que o método automático não funcionouMissing env: FIN_BASE_URL, unauthorized, auth_lookup_failed, ou tool fin_* não disponívelfin_listar_contas retorna OK) → pular essa skillAntes de tudo, confirme com a pessoa:
O fin-app-mcp roda via npx -y fin-app-mcp, que precisa de Node.js 18 ou superior. Sem Node, nada funciona.
Roda no terminal (via Bash):
node --version
Se retornar v18.x.x ou maior: OK, segue pro Passo 1.
Se retornar versão menor que 18:
Tu tem Node {versão} mas precisa de 18 ou maior. Atualiza assim:
- Baixa a versão LTS em https://nodejs.org
- Roda o instalador (next-next-finish)
- Reinicia o terminal (e o Claude se for Desktop)
- Roda
node --versionde novo pra confirmar- Volta aqui e me diz "atualizei"
Se retornar command not found / 'node' não é reconhecido como comando / similar:
Node.js não tá instalado no teu sistema. O
fin-app-mcpprecisa dele pra rodar.Como instalar (rápido, ~5 min):
Windows:
- Vai em https://nodejs.org
- Clica no botão "LTS" (versão recomendada)
- Baixa o
.mside Windows Installer- Abre o instalador, clica next-next-finish (deixa as opções padrão)
- Reinicia o Claude completamente (fecha tudo, incluindo a bandeja do sistema)
- Volta aqui e me diz "instalei o Node"
macOS:
- Opção 1 (sem terminal): vai em https://nodejs.org, baixa o
.pkgLTS, instala- Opção 2 (com Homebrew): no Terminal, roda
brew install node- Reinicia o Claude
- Me diz "instalei"
Linux:
- Recomendo instalar via
nvm: https://github.com/nvm-sh/nvm- Ou use o gerenciador de pacotes da tua distro (
apt,dnf, etc.) pra instalarnodejs >=18- Reinicia o Claude
- Me diz "instalei"
Não consigo instalar Node sozinho — é software do sistema operacional, precisa privilégio de admin que eu não tenho.
Pausa aqui. Não segue pro Passo 1 até a pessoa confirmar que instalou e o node --version retornar uma versão válida.
Quando ela voltar dizendo que instalou, roda node --version de novo pra confirmar antes de seguir.
Instrua a pessoa exatamente assim (não invente passos):
Você precisa gerar uma API key no FIN App. Faça o seguinte:
- Acesse https://fin-app-wine.vercel.app/settings/api-keys
- Faça login se ainda não estiver logada
- Clique em + Nova chave
- Dê um nome descritivo (ex: "Claude - {nome do computador}")
- Clique em Criar chave
- Copie a chave imediatamente (formato
fin_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)⚠️ A chave aparece uma única vez. Se perder, tem que revogar e gerar nova.
Quando tiver a chave em mãos, me avisa.
IMPORTANTE: quando a pessoa colar a chave na conversa, avise pra ela não fazer isso ("nunca cola chave aqui, ela fica gravada no histórico"). Peça pra ela ter a chave por perto mas não colar — você só precisa que ela cole no terminal ou no settings.json. Se ela já colou, siga adiante mas reforce que vai precisar revogar essa chave depois e gerar outra.
Pergunte ou detecte: a pessoa tá usando Claude Code (terminal) ou Claude Desktop (app)?
Pra detectar via shell: which claude retorna caminho se Code estiver instalado. No Desktop, a config fica em ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
Monte o comando exato e peça pra pessoa colar no terminal:
claude mcp add fin-app \
-s user \
-e FIN_BASE_URL=https://fin-app-wine.vercel.app \
-e FIN_API_KEY=fin_live_SUA_CHAVE_AQUI \
-- npx -y fin-app-mcp
Substitua fin_live_SUA_CHAVE_AQUI pela chave dela. NÃO peça pra ela colar a chave aqui na conversa pra você montar o comando. Mostre o template, peça pra ela substituir no terminal dela mesma.
A flag -s user instala globalmente (vale pra qualquer projeto).
A pessoa precisa editar claude_desktop_config.json manualmente. Localização:
~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonMostre o JSON pra adicionar:
{
"mcpServers": {
"fin-app": {
"command": "npx",
"args": ["-y", "fin-app-mcp"],
"env": {
"FIN_BASE_URL": "https://fin-app-wine.vercel.app",
"FIN_API_KEY": "fin_live_SUA_CHAVE_AQUI"
}
}
}
}
Avisos importantes:
mcpServers, adicione fin-app como mais uma entrada, não substitua o objeto inteirofin_live_SUA_CHAVE_AQUI pela chave real, no arquivo, fora da conversaPeça pra pessoa fechar completamente o Claude (Code ou Desktop) e abrir de novo. A primeira invocação demora alguns segundos porque o npx -y fin-app-mcp baixa o pacote do npm na primeira vez.
No Claude Code: peça pra rodar no terminal:
claude mcp list
Procure por fin-app na lista. Deve aparecer como conectado.
No Claude Desktop: peça pra ela voltar pra conversa e pedir pro Claude fazer um teste simples. Você pode rodar fin_listar_contas direto. Se retornar lista (mesmo vazia), tá funcionando.
Chame fin_listar_contas. Se retornar OK (lista vazia ou com contas), instalação concluída. Diga:
Pronto, MCP do FIN tá instalado e funcionando. Quer rodar o onboarding agora? (
/financeiro:onboarding)
Quando der erro, identifique pelo sintoma e responda:
| Sintoma | Causa | Solução |
|---|---|---|
claude mcp list não mostra fin-app | Config não foi salva, ou Claude Code não foi reiniciado | Verifique ~/.claude/settings.json (ou claude_desktop_config.json), reinicie Claude completamente |
Missing env: FIN_BASE_URL | Env var não foi setada na config | Reabra a config e confira que env tem FIN_BASE_URL E FIN_API_KEY |
unauthorized | API key errada, expirada ou revogada | Vá em https://fin-app-wine.vercel.app/settings/api-keys, gere nova chave, atualize a config |
auth_lookup_failed | Problema temporário no Supabase do FIN | Tente de novo em alguns segundos. Se persistir, verifique se o app tá no ar |
npx muito lento na 1ª invocação | Normal — baixando pacote (~16KB + deps) | Aguarde. Próximas invocações são instantâneas. Se >30s consistentemente, npm cache clean --force |
Tools fin_* ainda não aparecem após reiniciar | Cache do Claude, ou config em local errado | Confira que o JSON está válido (use jq < ~/.claude/settings.json), reinicie de novo |
Se a pessoa colou a chave em algum lugar público (incluindo essa conversa), avise:
Financeiro/ ou em config do pluginsettings.json do Claude Code ou no claude_desktop_config.json do DesktopO npx -y fin-app-mcp sempre baixa a última versão do pacote npm. Quando a Anthropic ou o time do FIN publicar uma nova versão, ela vai entrar automaticamente na próxima invocação. A pessoa não precisa fazer nada.
Pra forçar uma versão específica, ela pode trocar fin-app-mcp por [email protected] (ou outra versão) nos args da config.
Diga pra pessoa o que fazer a seguir:
MCP do FIN instalado. Próximo passo: configurar suas contas e cartões no FIN. Rode
/financeiro:onboardingou só me diga "vamos configurar minhas finanças".
npx claudepluginhub pe-menezes/fin-claude-plugin --plugin financeiroProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.