Skip to main content

mcp-investidor10-wallet

Assistente de investimentos que conecta um agente (Claude Code, Devin CLI, Codex, Gemini CLI) a uma carteira pública do Investidor10, com memória de longo prazo do investidor (teses, regras, decisões, insights), alertas de preço e um plugin de comportamento (skills, guardião de disciplina, persona e lembrete de memória).

Sem frontend — a interface é o cliente do agente. O servidor roda sobre stdio (o cliente inicia o processo; nenhuma porta é exposta).

Aviso: a fonte de dados é a API interna, não documentada, do Investidor10. Ela é pública e sem autenticação hoje, mas pode mudar ou ser desligada sem aviso. Falhas aparecem como erros estruturados explícitos — nunca como valores inventados.

Status

Roadmap: docs/ROADMAP.md.

As 19 tools estão implementadas (6 de dados da carteira/mercado + 13 de memória/alertas) — contratos completos em specs/001-mcp-investidor10-wallet/contracts/mcp-tools.md.

Instalação automática (recomendada)

Pré-requisito: uv (que traz Python 3.11+).

Um comando instala o produto completo — registra o servidor MCP e instala o plugin de comportamento nos CLIs de agente presentes na máquina (Claude Code, Devin CLI, Codex, Gemini CLI):

uvx mcp-investidor10-wallet install

O assistente pergunta apenas o ID da carteira (ver abaixo), valida que ela é pública e cuida do resto, com relatório em PT-BR.

Opções:

Flag Efeito
--mcp-only Registra apenas o servidor MCP (sem o plugin) — modo técnico
--dry-run Simula e relata o que faria, sem alterar nada
--clients claude,devin,codex,gemini Restringe os clientes alvo
--wallet-id <id> Informa o ID sem pergunta (scripts/CI)
--yes Pula confirmações de rotina

O plugin de comportamento

O bundle inclui, além do servidor:

  • 3 skills (/analise-da-carteira, /check-de-tese, /resumo-de-dividendos) — roteiros com as regras do produto embutidas (bootstrap da memória, atraso de ~15 min das cotações, rendimento recorrente e nunca DY médio);
  • guardião de disciplina — subagente read-only que confronta decisões de investimento com as regras e teses que você salvou na memória;
  • persona — instruções de papel injetadas no início de cada sessão;
  • lembrete de memória — ao fim da sessão, propõe registrar decisões discutidas (sempre com sua confirmação; nunca grava sozinho).

Instalação manual do plugin (sem o assistente):

# Claude Code
claude plugin marketplace add rc-ventura/mcp-investidor10-wallet
claude plugin install investidor10-carteira@investidor10

# Devin CLI
devin plugins install rc-ventura/mcp-investidor10-wallet#plugin -y

# Codex CLI
codex plugin marketplace add rc-ventura/mcp-investidor10-wallet
codex plugin add investidor10-carteira@investidor10

# Gemini CLI
gemini extensions install https://github.com/rc-ventura/mcp-investidor10-wallet

Onde encontrar o seu WALLET_ID

Abra sua carteira no Investidor10 e copie o número da URL pública:

https://investidor10.com.br/carteira/SEU_ID

A carteira precisa ser pública — nas configurações do Investidor10, ative "carteira pública". O ID é o único identificador que o servidor usa; quem tiver o ID consegue ler os valores da carteira (o botão de mascarar do site é apenas cosmético — a API continua retornando tudo).

Configuração manual (sem o assistente)

O cliente do agente inicia o servidor como processo filho; por isso o comando configurado precisa existir no ambiente do cliente.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) — apps GUI no macOS não herdam o PATH do shell: use o caminho absoluto do uv (descubra com which uv):

{
  "mcpServers": {
    "carteira": {
      "command": "/Users/<seu-usuario>/.local/bin/uv",
      "args": ["tool", "run", "mcp-investidor10-wallet"],
      "env": { "WALLET_ID": "SEU_ID" }
    }
  }
}

Claude Code:

claude mcp add carteira --scope user -- env WALLET_ID=SEU_ID uvx mcp-investidor10-wallet

Devin CLI:

devin mcp add -s user carteira -e WALLET_ID=SEU_ID -- uvx mcp-investidor10-wallet

Codex CLI:

codex mcp add carteira --env WALLET_ID=SEU_ID -- uvx mcp-investidor10-wallet

Gemini CLI:

gemini mcp add -s user -e WALLET_ID=SEU_ID carteira uvx mcp-investidor10-wallet

O cliente reinicia o servidor a cada sessão; depois de uma atualização, reinicie a sessão para carregar tools novas.

Solução de problemas

Sintoma Causa provável Correção
"MCP failed to connect" (Claude Desktop) PATH do shell não existe no app GUI Use o caminho absoluto do uv (veja acima; which uv para descobrir)
WALLET_ID não configurado + saída WALLET_ID ausente na config do cliente Adicione WALLET_ID no bloco env do servidor
Carteira ... não encontrada ou não é pública ID errado ou carteira privada Confira o ID na URL pública e deixe a carteira pública nas configurações do site
Não foi possível validar a carteira ... (fonte indisponível) API fora do ar ou sem rede Aviso não-bloqueante: o servidor sobe e as tools de dados informarão o erro
Não foi possível migrar a memória ... Permissões de ~/.investidor10/ Corrija as permissões do diretório indicado e reinicie

Onde ficam os dados

  • Memória: ~/.investidor10/memory.json — arquivo local versionado com escrita atômica, compartilhado por todos os clientes da máquina. A instalação anterior (memória no diretório de trabalho) é migrada automaticamente na primeira execução, com aviso no stderr.
  • Cache de API: apenas em memória de processo (TTL configurável).
  • Nada é enviado a outro lugar pelo servidor — os resultados das tools entram no contexto do seu provedor de LLM (o agente), como qualquer tool.

Configuração (variáveis de ambiente)

Variável Obrigatória Default Uso
WALLET_ID Sim — ID público da carteira (o servidor aborta sem ela)
WALLET_MEMORY_PATH Não ~/.investidor10/memory.json Caminho da memória (override sem migração)
WALLET_CACHE_TTL_SECONDS Não 600 TTL do cache em memória
WALLET_CACHE_MAX_STALE_SECONDS Não 86400 Idade máxima de cache expirado servido em queda da fonte (24h); mais antigo vira erro explícito

Tools (19)

  • Dados da carteira/mercado (6): get_wallet_summary, get_wallet_allocation, get_wallet_positions, get_patrimony_history, get_earnings, get_asset_quote
  • Memória e alertas (13): get_session_context (bootstrap da sessão — chame no início de toda sessão), get_wallet_goal, set_wallet_goal, save_thesis, get_theses, save_rule, get_rules, log_decision, record_decision_outcome, log_insight, create_price_alert, list_price_alerts, cancel_price_alert

Testes

uv run pytest          # unit + contrato (API mockada com respx)
uv run pytest -m live  # integração opt-in contra a API real

Limitações e riscos

  • API interna não documentada: endpoints públicos mas sem contrato; podem mudar ou passar a exigir autenticação sem aviso.
  • Cobertura de cotação: get_asset_quote só cobre ações B3; FIIs, ETFs internacionais, cripto e tesouro retornam asset_type_not_supported (ver learning lesson). Ativos dessas classes na carteira aparecem via get_wallet_positions.
  • Detalhe de proventos: get_earnings retorna o total do período; a tabela por pagamento existe no upstream e é candidata a uma tool futura (ver learning lesson).
  • Cotações com atraso (~15 min na B3) — o agente deve sempre mencionar.
  • Uso pessoal/educacional: o agente sugere, nunca executa ordens.

Metadata

Release files for mcp-investidor10-wallet 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-investidor10-wallet 0.2.0
File Size Uploaded Provenance Actions
mcp_investidor10_wallet-0.2.0.tar.gz 376.5 kB With provenance Details for mcp_investidor10_wallet-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-investidor10-wallet 0.2.0
File Interpreter ABI Platform Actions
mcp_investidor10_wallet-0.2.0-py3-none-any.whl Python 3 none any Details for mcp_investidor10_wallet-0.2.0-py3-none-any.whl

Total release size: 406.0 kB

Release files / mcp_investidor10_wallet-0.2.0.tar.gz

Download URL mcp_investidor10_wallet-0.2.0.tar.gz
Size 376.5 kB
Tags Source
SHA-256 checksum
How to use checksums
91db35ecf0010ff198057e23be04f548bbd10f2c5b875b0b18f74d96d0d1e80b
BLAKE2b-256 checksum
How to use checksums
130851ee0b4e196cc4f3b813b86355f769cc40eb5f5e784fbc7b2592927ece35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Release files / mcp_investidor10_wallet-0.2.0-py3-none-any.whl

Download URL mcp_investidor10_wallet-0.2.0-py3-none-any.whl
Size 29.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c7643162dd76c61d20a4dd492ac2ae93e9126730f0aae4a1cf6ebcfd86ca808
BLAKE2b-256 checksum
How to use checksums
f3bd8779767d21e7fb20669f023b11673f66745e7ab6b54031099fad1f15b75a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

Security for mcp-investidor10-wallet 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_investidor10_wallet-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page