Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

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.

Privacidade: leia docs/PRIVACY.md antes de instalar. Ele explica o que vai para onde, por que o ID da carteira deve ser tratado como senha e como o modo privacidade (WALLET_MASK_VALUES) evita que valores em reais cheguem ao modelo.

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.

O servidor fica registrado na versão exata do assistente (uvx mcp-investidor10-wallet@<versão>), e não na mais recente do PyPI a cada abertura. Para atualizar, rode uvx mcp-investidor10-wallet@latest install de novo.

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 preparar o diretório de 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. Vários clientes abertos ao mesmo tempo não perdem gravações: o servidor controla o acesso ao arquivo (memory.json.lock) e mantém um histórico de cada mudança (memory.json.log). Para quem tinha a memória no diretório do repositório: mova o arquivo com mv ./memory.json ~/.investidor10/memory.json ou defina WALLET_MEMORY_PATH.
  • Pasta sincronizada (Dropbox, iCloud, OneDrive): segura na mesma máquina; usar a mesma memória em duas máquinas ao mesmo tempo não é protegido (a sincronização pode gerar uma cópia em conflito). Use uma máquina por vez.
  • 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 (use um disco local)
WALLET_MASK_VALUES Não desligado 1/true/yes/on ligam o modo privacidade: valores em R$ e quantidades não chegam ao modelo (ver PRIVACY.md)
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.4.0rc1

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.4.0rc1
File Size Uploaded Provenance Actions
mcp_investidor10_wallet-0.4.0rc1.tar.gz 50.6 kB With provenance Details for mcp_investidor10_wallet-0.4.0rc1.tar.gz

Built distribution (wheel)

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

Total release size: 101.7 kB

Release files / mcp_investidor10_wallet-0.4.0rc1.tar.gz

Download URL mcp_investidor10_wallet-0.4.0rc1.tar.gz
Size 50.6 kB
Tags Source
SHA-256 checksum
How to use checksums
acdf357c72e3c24ecd6e969d37083865f8871c144b5662f8b5e4cfbf1aaaa0fc
BLAKE2b-256 checksum
How to use checksums
b92a54e687eef9e5c36551b449f3483054c713f48688f8aa02fd91bdae2d237e
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 Nov 7, 2026.

Transparency log

Release files / mcp_investidor10_wallet-0.4.0rc1-py3-none-any.whl

Download URL mcp_investidor10_wallet-0.4.0rc1-py3-none-any.whl
Size 51.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
528da3a26d78e9dfa133720fc87f6807f7f3c704e2a20163267dcb546a6ed66f
BLAKE2b-256 checksum
How to use checksums
50b82e907af3b869b8ae6f489e2b065b481c026dc88eed98fde5abf69e1f40bf
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 Nov 7, 2026.

Transparency log

Security for mcp-investidor10-wallet 0.4.0rc1

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.4.0rc1.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 Nov 7, 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