MCP Client for Ollama

Um cliente Python que conecta LLMs locais via Ollama a servidores Model Context Protocol, permitindo que eles usem ferramentas.

GitHub

826

Experimente este MCPPatrocinado

Documentação

Um cliente Python simples, porém poderoso, para interagir com servidores Model Context Protocol (MCP) usando Ollama, permitindo que você aproveite LLMs locais para execução avançada de ferramentas.

English | 简体中文 | Español

MCP Client for Ollama (ollmcp)

Pepy Total Downloads

_{Patrocinado por}

_{Aprenda como usar o Atlas Cloud com ollmcp na seção Patrocinadores}

MCP Client for Ollama Demo

🎥 Assista a esta demonstração como uma gravação Asciinema

Sumário

Visão Geral
Recursos
Requisitos
Início Rápido
Opções de Instalação
Solução de Problemas
✨NOVO Gerenciando Servidores MCP via CLI
Comandos Interativos
Recursos de Autocompletar e Prompts
Gerenciamento de Configuração
- ✨NOVO Perfis por provedor
Formato de Configuração do Servidor
- Dicas: Onde Colocar as Configurações do Servidor MCP e um Exemplo Funcional
Modelos Compatíveis
- Modelos Ollama Cloud
✨NOVO Patrocinadores
- Atlas Cloud
- Torne-se um patrocinador
Onde Posso Encontrar Mais Servidores MCP?
Projetos Relacionados
Segurança
Licença
Agradecimentos

Visão Geral

MCP Client for Ollama (ollmcp) é um aplicativo de terminal interativo moderno (TUI) construído para engenharia de harness, conectando LLMs locais do Ollama a um ou mais servidores Model Context Protocol (MCP). Ao suportar totalmente os primitivos principais do MCP (ferramentas, prompts e recursos), ele fornece um espaço de terminal controlado onde você direciona e o agente executa. Com uma interface rica e amigável, ele permite que você gerencie sua configuração com segurança em tempo real, sem necessidade de codificação. Seja você construindo, testando ou explorando, este cliente otimiza seu fluxo de trabalho com recursos como autocompletar difuso, configuração avançada de modelo, recarregamento a quente de servidores MCP para desenvolvimento rápido e controles rigorosos de segurança com Supervisão Humana.

Recursos

🤖 Modo Agente: Execução iterativa de ferramentas quando os modelos solicitam múltiplas chamadas de ferramentas, com um limite de loop configurável e escolhas interativas quando o limite é atingido (continuar, concluir ou abortar)
🌐 Suporte a Múltiplos Servidores: Conecte-se a vários servidores MCP simultaneamente
🚀 Múltiplos Tipos de Transporte: Suporta conexões de servidor STDIO, SSE e HTTP Streamable
📋 Suporte a Prompts MCP: Navegue, invoque e gerencie prompts de servidores MCP com coleta de argumentos, pré-visualização e reversão segura
📦 Suporte a Recursos MCP: Navegue e leia dados contextuais de servidores MCP, incluindo arquivos, documentos e dados estruturados
☁️ Suporte a Ollama Cloud: Funciona perfeitamente com modelos Ollama Cloud para chamadas de ferramentas, permitindo acesso a modelos poderosos hospedados na nuvem enquanto usa ferramentas MCP locais
🌍 Múltiplos Provedores de LLM: Use Ollama (padrão) ou provedores compatíveis com OpenAI (OpenAI, OpenRouter, DeepSeek, etc.), com configurações de conexão lembradas por provedor
🎨 Interface de Terminal Rica: Console interativo com estilo moderno
🌊 Respostas em Streaming: Veja as saídas do modelo em tempo real enquanto são geradas
📝 Modos de Exibição de Resposta: Alterne entre visualizações de resposta Simples, Markdown, Ambas ou Markdown (blocos) durante o streaming
🛠️ Gerenciamento de Ferramentas: Habilite/desabilite ferramentas específicas ou servidores inteiros durante sessões de chat
🧑‍💻 Supervisão Humana (HIL): Revise e aprove execuções de ferramentas antes de serem executadas para maior controle e segurança
🎮 Configuração Avançada de Modelo: Ajuste finamente mais de 15 parâmetros de modelo, incluindo tamanho da janela de contexto, temperatura, amostragem, controle de repetição e mais
💬 Personalização do Prompt do Sistema: Defina e edite o prompt do sistema para controlar o comportamento e a persona do modelo
🧠 Controle da Janela de Contexto: Ajuste o tamanho da janela de contexto (num_ctx) para lidar com conversas mais longas e tarefas complexas
🎨 Exibição Aprimorada de Ferramentas: Visualização bonita e estruturada de execuções de ferramentas com realce de sintaxe JSON
🧠 Gerenciamento de Contexto: Controle a memória da conversa com configurações de retenção ajustáveis
🤔 Modo de Pensamento: Capacidades avançadas de raciocínio com processos de pensamento visíveis para modelos suportados (por exemplo, gpt-oss, deepseek-r1, qwen3, etc.)
💪 Níveis de Esforço de Raciocínio: Defina o esforço de raciocínio como automático, mínimo, baixo, médio, alto ou extra alto para modelos suportados
🖼️ Suporte a Ferramentas de Visão: Imagens retornadas por ferramentas são automaticamente encaminhadas para modelos com capacidade de visão
🗣️ Suporte a Múltiplas Linguagens: Trabalhe perfeitamente com servidores MCP em Python e JavaScript
📜 Gerenciamento de Histórico: Veja o histórico completo da conversa, exporte para JSON para backup/análise e importe sessões anteriores para continuidade
🔍 Descoberta Automática: Encontre e use automaticamente as configurações existentes de servidores MCP do Claude
🔁 Troca Dinâmica de Modelo: Alterne entre qualquer modelo Ollama instalado sem reiniciar
💾 Persistência de Configuração: Salve e carregue preferências de ferramentas e configurações de modelo entre sessões
🔄 Recarregamento de Servidor: Recarregue a quente servidores MCP durante o desenvolvimento sem reiniciar o cliente
✨ Autocompletar Difuso: Autocompletar interativo de comandos com setas e descrições
🏷️ Prompt Dinâmico: Mostra o modelo atual, modo de pensamento e ferramentas habilitadas
📊 Métricas de Desempenho: Dados detalhados de desempenho do modelo após cada consulta, incluindo tempos de duração e contagens de tokens
🔌 Plug-and-Play: Funciona imediatamente com servidores de ferramentas padrão compatíveis com MCP
🔔 Notificações de Atualização: Detecta automaticamente quando uma nova versão está disponível
🖥️ CLI Moderno com Typer: Opções agrupadas, autocompletar de shell e saída de ajuda aprimorada
⏹️ Abortar Geração: Você pode abortar a geração do modelo a qualquer momento pressionando 'a' durante o streaming da resposta

Requisitos

Python 3.11+ (Guia de instalação)
Ollama rodando localmente (Guia de instalação)
- Após a instalação, execute ollama list para ver os modelos disponíveis. Se nenhum modelo estiver instalado, você pode baixar um usando ollama pull <model_name>. Por exemplo, ollama pull gemma4:latest.
Gerenciador de pacotes UV (Guia de instalação)

Início Rápido

Instale ollmcp via pip, adicione um servidor MCP e execute o cliente:

# Install ollmcp via uv
uv tool install --upgrade ollmcp
# or via pip
pip install --upgrade ollmcp
# Add an MCP server (example: playwright stdio server)
ollmcp mcp add playwright -- npx @playwright/mcp@latest
# Run the client (check optional flags with `ollmcp --help`)
ollmcp # once running, use /help for interactive commands

Opções de Instalação

Opção 1: Instale com uv e execute (recomendado)

uv tool install --upgrade ollmcp
ollmcp

Opção 2: Instale com pip e execute

pip install --upgrade ollmcp
ollmcp

Opção 3: Apenas execute sem instalar (requer o gerenciador de pacotes uv)

uvx ollmcp

Opção 4: Instale a partir do código-fonte e execute usando ambiente virtual

git clone https://github.com/jonigl/mcp-client-for-ollama.git
cd mcp-client-for-ollama
uv run -m mcp_client_for_ollama

Solução de Problemas

`Could not find a version that satisfies the requirement ollmcp (from versions: none)`

Isso quase sempre significa que o Python que você está usando é mais antigo que o 3.11+ necessário. Isso é comum no macOS, onde o Python do sistema (/usr/bin/python3) ou o Python incluído no Xcode pode ser 3.9 ou mais antigo. Quando nenhuma versão corresponde a requires-python >= 3.11, o pip filtra todas as versões e relata a mensagem enganosa "from versions: none".

Primeiro verifique sua versão:

python3 --version   # must be 3.11 or newer

Em seguida, instale com um Python moderno. A opção mais simples é uv, que busca um Python adequado automaticamente para você:

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, make sure to use a Python 3.11+ interpreter:
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

Dê uma olhada nas Opções de Instalação.

`error: externally-managed-environment` (PEP 668)

Em Debian/Ubuntu recentes (Python 3.12+), o pip do sistema é intencionalmente bloqueado para proteger pacotes gerenciados pelo SO, então pip install ollmcp é bloqueado. Isso é uma política do sistema (PEP 668), não um problema do ollmcp. Instale-o em um ambiente isolado:

uv tool install --upgrade ollmcp   # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, use a virtual environment:
python3.11 -m venv ollmcp-env
source ollmcp-env/bin/activate
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp

Dê uma olhada nas Opções de Instalação.

[!WARNING] Evite pip install --break-system-packages ollmcp. Funciona, mas instala no Python do sistema e pode quebrar pacotes dos quais seu SO depende.

Gerenciando Servidores MCP via CLI

O ollmcp pode gerenciar suas próprias configurações de servidores MCP diretamente da linha de comando, semelhante ao claude mcp:

# Remote servers (Streamable HTTP or SSE)
ollmcp mcp add --transport http <name> <url>
ollmcp mcp add --transport sse <name> <url>

# Local stdio servers - everything after `--` is the command to run
ollmcp mcp add [options] <name> -- <command> [args...]

# List configured servers
ollmcp mcp list

# Remove a server
ollmcp mcp remove <name>

# For more details on options and usage, run:
ollmcp mcp --help
ollmcp mcp add --help

Exemplos:

[!TIP] Depois de adicionar alguns servidores, basta executar ollmcp para conectar-se a eles automaticamente.

ollmcp mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $YOUR_GITHUB_PAT"
ollmcp mcp add --transport stdio playwright npx @playwright/mcp@latest
ollmcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /allowed-dir1 ~/allowed-dir2 # stdio transport by default
ollmcp mcp add --env API_KEY=YOUR_KEY --transport sse my-sse-server http://localhost:8000/sse

Opções do mcp add

--transport, -t: stdio (padrão), sse ou http.
--header, -H: Cabeçalho HTTP como "Name: Value" para servidores sse/http. Repetível.
--env, -e: Variável de ambiente como KEY=value para servidores stdio. Repetível.
--scope, -s: Onde armazenar o servidor (veja os escopos abaixo). Padrão: local.

Escopos

Escopo	Carregado em	Compartilhado com a equipe	Armazenado em
`local`	Apenas no projeto atual	Não	`~/.config/ollmcp/mcp.local.json` (chaveado pelo caminho do projeto)
`project`	Apenas no projeto atual	Sim (via VCS)	`.mcp.json` na raiz do projeto
`user`	Todos os seus projetos	Não	`~/.config/ollmcp/mcp.json`

O escopo project escreve um arquivo .mcp.json padrão na raiz do seu projeto, compatível com Claude Code e outras ferramentas que entendem MCP. Se o mesmo nome de servidor existir em vários escopos, a precedência é local > project > user.

[!NOTE] Servidores adicionados via ollmcp mcp add são sempre carregados como camada base. Quaisquer flags (--mcp-server, --mcp-server-url, --servers-json, --claude-desktop) são adicionadas por cima. Para incluir servidores do Claude Desktop, passe --claude-desktop explicitamente.

Se um servidor com o mesmo nome também for fornecido por uma dessas flags, ambas as conexões são abertas atualmente, mas apenas uma é mantida ativa sob esse nome. Evite reutilizar o nome de um servidor do registro em --mcp-server/--mcp-server-url/--servers-json/--claude-desktop.

Argumentos de Linha de Comando

[!TIP] A CLI agora usa Typer para uma experiência moderna: opções agrupadas, ajuda rica e autocompletar de shell integrado. Usuários avançados podem usar flags curtas para comandos mais rápidos. Para habilitar o autocompletar, execute:
ollmcp --install-completion
Em seguida, reinicie o shell ou siga as instruções impressas.

Configuração do Servidor MCP:

--mcp-server, -s: Caminho para um ou mais scripts de servidor MCP (.py ou .js). Pode ser especificado várias vezes.
--mcp-server-url, -u: URL para um ou mais servidores MCP SSE ou Streamable HTTP. Pode ser especificado várias vezes. Veja Caminhos de endpoint MCP comuns para endpoints típicos.
--servers-json, -j: Caminho para um arquivo JSON com configurações de servidor. Veja Formato de Configuração de Servidor para detalhes.
--claude-desktop: Carrega servidores do arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json). Mesclado com servidores adicionados via ollmcp mcp add e quaisquer outras flags.

[!IMPORTANT] Mudança significativa: --auto-discovery / -a foi substituído por --claude-desktop. Além disso, servidores adicionados via ollmcp mcp add agora são sempre carregados automaticamente; eles não são mais um fallback que desaparece quando outras flags são usadas. Servidores do Claude Desktop nunca são carregados automaticamente; use --claude-desktop para incluí-los.

Configuração do Provedor de Inferência:

--model, -m MODEL: Modelo a ser usado. Padrão: o modelo da sua configuração salva, se definido; caso contrário, o primeiro modelo disponível no Ollama
--provider, -p PROVIDER: Provedor de LLM a ser usado (ex.: ollama, openai, atlascloud, openrouter, deepseek). Padrão: ollama
--host, -H HOST: Host do LLM / URL base da API. Padrão: http://localhost:11434 do Ollama para o provedor ollama, ou o endpoint padrão do próprio provedor caso contrário.
--api-key, -k KEY: Chave de API para o provedor de LLM. Também lida da variável de ambiente $OLLMCP_API_KEY, que é agnóstica de provedor (aplica-se a qualquer provedor que você selecionar com --provider). Chaves passadas via $OLLMCP_API_KEY nunca são gravadas no arquivo de configuração; apenas chaves passadas com --api-key são salvas. Não é necessário para ollama.

[!NOTE] Provedores atualmente suportados: ollama, openai, atlascloud e qualquer provedor compatível com OpenAI (openrouter, deepseek, perplexity, etc.). Mais provedores em breve.

Opções Gerais:

--version, -v: Mostra a versão e sai
--help, -h: Mostra a mensagem de ajuda e sai
--install-completion: Instala scripts de autocompletar de shell para o cliente
--show-completion: Mostra as opções de completar de shell disponíveis

Registro de Log do Servidor MCP:

Tudo o que um servidor MCP reporta é gravado em ~/.config/ollmcp/logs/<session>/<server>.log, um diretório por execução, mantendo os últimos 5. Nada que um servidor imprime chega à tela, a menos que você peça — caso contrário, desenharia sobre a resposta que está sendo transmitida.

Os servidores reportam por dois canais: seu stderr (apenas servidores stdio, já que um remoto roda em outro lugar) e notificações de log MCP (qualquer servidor). Ambas as flags apenas mudam o que você vê na tela — o arquivo de log recebe tudo de qualquer forma:

	gravado no arquivo de log	mostrado na tela
(sem flag)	tudo o que o servidor envia	nada do servidor
`--debug`	tudo o que o servidor envia	tudo, conforme chega
`--log-level LEVEL`	tudo o que o servidor envia	apenas notificações de LEVEL ou superior
`--debug --log-level LEVEL`	tudo o que o servidor envia	stderr completo + notificações de LEVEL ou superior

LEVEL é um de debug, info, notice, warning, error, critical, alert, emergency.

Sem flag, nenhum nível é solicitado: o servidor decide o que emite e tudo é registrado. --log-level filtra o que você vê e também é enviado ao servidor (logging/setLevel) quando ele anuncia a capacidade de logging — tal servidor pode então parar de emitir os níveis mais baixos, que também ficam ausentes do arquivo. Servidores sem essa capacidade continuam enviando tudo, e a filtragem acontece aqui.

Quando um servidor falha ao conectar, o erro aponta para seu arquivo de log: tudo o que o servidor imprimiu em sua saída está lá, e essa geralmente é a razão real.

[!NOTE] O que o próprio ollmcp reporta vai para ~/.config/ollmcp/logs/<session>/ollmcp.log, ao lado dos arquivos do servidor. É gravado em toda execução, sem necessidade de --debug, e é o arquivo para o qual o aviso na tela aponta quando um fluxo de resposta termina cedo. Trabalho em andamento: por enquanto registra principalmente erros de provedor e streaming, e mais será registrado lá ao longo do tempo.

Provedores de Inferência Suportados

[!WARNING] Provedores não-Ollama são experimentais. O suporte para provedores diferentes do Ollama foi adicionado recentemente e ainda está sendo estabilizado; nem tudo pode funcionar corretamente ainda.

ollmcp funciona com Ollama além de qualquer provedor compatível com OpenAI que o any-llm expõe. Selecione um com --provider. Forneça a chave com --api-key ou $OLLMCP_API_KEY (ambos funcionam para qualquer provedor selecionado) ou via a variável de ambiente nativa do provedor mostrada abaixo. $OLLMCP_API_KEY e as variáveis de ambiente nativas do provedor nunca são gravadas em disco; apenas uma chave passada com --api-key é salva na configuração.

Provedor (`--provider`)	Variável de ambiente da chave de API
`ollama` (padrão)	- (local)
`atlascloud`	`ATLASCLOUD_API_KEY`
`azureopenai`	`AZURE_OPENAI_API_KEY`
`dashscope`	`DASHSCOPE_API_KEY`
`databricks`	`DATABRICKS_TOKEN`
`deepinfra`	`DEEPINFRA_API_KEY`
`deepseek`	`DEEPSEEK_API_KEY`
`fireworks`	`FIREWORKS_API_KEY`
`gateway`	`GATEWAY_API_KEY`
`inception`	`INCEPTION_API_KEY`
`llama`	`LLAMA_API_KEY`
`llamacpp`	- (local)
`llamafile`	- (local)
`lmstudio`	`LM_STUDIO_API_KEY`
`minimax`	`MINIMAX_API_KEY`
`moonshot`	`MOONSHOT_API_KEY`
`mzai`	`ANY_LLM_KEY`
`nebius`	`NEBIUS_API_KEY`
`openai`	`OPENAI_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`perplexity`	`PERPLEXITY_API_KEY`
`portkey`	`PORTKEY_API_KEY`
`qiniu`	`QINIU_API_KEY`
`sambanova`	`SAMBANOVA_API_KEY`
`vllm`	`VLLM_API_KEY`
`zai`	`ZAI_API_KEY`

[!NOTE] Servidores locais compatíveis com OpenAI (ollama, llamacpp, llamafile, lmstudio, vllm) normalmente rodam sem chave de API; aponte ollmcp para eles com --host. Provedores que o any-llm oferece que não são compatíveis com OpenAI (ex.: anthropic, gemini, mistral, groq, cohere) ainda não são suportados.

[!WARNING] Limitação de detecção de capacidade: ollmcp apenas lê capacidades reais por modelo (tools, vision, thinking) do Ollama. Para todo provedor não-Ollama, todas as três capacidades são atualmente assumidas como disponíveis e mostradas como tal na lista de modelos e emblemas, então um modelo pode ser reportado como suportando ferramentas, visão ou pensamento mesmo quando não suporta. Se um modelo não tiver uma capacidade, a API do provedor retornará um erro quando você tentar usá-la.

Ordem de resolução da chave de API

Para o provedor selecionado, ollmcp resolve a chave de API nesta ordem, da precedência mais alta para a mais baixa:

A flag --api-key / -k.
A variável de ambiente $OLLMCP_API_KEY (agnóstica de provedor, aplica-se a qualquer provedor que você selecionou com --provider).
A chave por provedor salva em ~/.config/ollmcp/config.json (presente apenas se foi passada uma vez via --api-key).
A variável de ambiente nativa do próprio provedor, detectada pelo any-llm (ex.: OPENAI_API_KEY, OPENROUTER_API_KEY).

[!WARNING] Uma chave por provedor salva (3) tem precedência sobre a variável de ambiente nativa do provedor (4). Portanto, se você salvou anteriormente uma chave errada ou expirada, definir OPENAI_API_KEY (ou o equivalente) sozinho não a substituirá. Para corrigir, passe a chave correta com --api-key, ou remova o apiKey desatualizado do perfil desse provedor em ~/.config/ollmcp/config.json.

Exemplos de Uso

A maneira mais simples de executar o cliente:

ollmcp

[!TIP] Isso conecta a todos os servidores registrados via ollmcp mcp add e usa o modelo do seu arquivo de configuração salvo, ou o primeiro modelo disponível no Ollama se nenhum estiver salvo. Passe --claude-desktop para também incluir servidores da configuração do Claude Desktop.

Conectar a um único servidor:

ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b
# Or using short flags:
ollmcp -s /path/to/weather.py -m llama3.2:3b

Conectar a vários servidores:

ollmcp --mcp-server /path/to/weather.py --mcp-server /path/to/filesystem.js
# Or using short flags:
ollmcp -s /path/to/weather.py -s /path/to/filesystem.js

[!TIP] Se --model não for especificado, o modelo do seu arquivo de configuração salvo é usado; caso contrário, o primeiro modelo disponível no Ollama é selecionado automaticamente (você será informado sobre como baixar um se nenhum estiver instalado).

Use um arquivo de configuração JSON:

ollmcp --servers-json /path/to/servers.json --model llama3.2:1b
# Or using short flags:
ollmcp -j /path/to/servers.json -m llama3.2:1b

[!TIP] Veja a seção Formato de Configuração de Servidor para detalhes sobre como estruturar o arquivo JSON.

Use um host Ollama personalizado:

ollmcp --host http://localhost:22545 --servers-json /path/to/servers.json
# Or using short flags:
ollmcp -H http://localhost:22545 -j /path/to/servers.json

Use um provedor de LLM diferente (OpenAI ou qualquer API compatível com OpenAI):

ollmcp --provider openai --api-key $OPENAI_API_KEY --model gpt-5.5
# OpenAI-compatible providers (e.g. OpenRouter, DeepSeek); override the endpoint with --host if needed:
ollmcp --provider openrouter --api-key $OPENROUTER_API_KEY -m openrouter/free

[!TIP] As configurações do provedor (modelo, host, chave de API) são lembradas por provedor. Uma vez salvas com /save-config, o simples ollmcp retoma seu último provedor usado. Veja Gerenciamento de Configuração para detalhes.

Conecte a servidores SSE ou Streamable HTTP por URL:

ollmcp --mcp-server-url http://localhost:8000/sse --model qwen2.5:latest
# Or using short flags:
ollmcp -u http://localhost:8000/sse -m qwen2.5:latest

Conecte a vários servidores por URL:

ollmcp --mcp-server-url http://localhost:8000/sse --mcp-server-url http://localhost:9000/mcp
# Or using short flags:
ollmcp -u http://localhost:8000/sse -u http://localhost:9000/mcp

Misture scripts locais e servidores por URL:

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --model qwen3:1.7b
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp -m qwen3:1.7b

Inclua servidores do Claude Desktop junto com outras fontes:

ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --claude-desktop
# Or using short flags:
ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp --claude-desktop

Como Funcionam as Chamadas de Ferramentas

O cliente envia sua consulta para o Ollama com uma lista de ferramentas disponíveis
Se o Ollama decidir usar uma ferramenta, o cliente:
- Exibe a execução da ferramenta com argumentos formatados e realce de sintaxe
- Mostra um prompt de confirmação Human-in-the-Loop (se ativado) permitindo que você revise e aprove a chamada da ferramenta
- Extrai o nome da ferramenta e os argumentos da resposta do modelo
- Chama o servidor MCP apropriado com esses argumentos (somente se aprovado ou se o HIL estiver desativado)
- Mostra a resposta da ferramenta em um formato estruturado e fácil de ler (incluindo resumos de imagens e mídia não suportada)
- Se a ferramenta retornou imagens e o modelo atual suporta visão, anexa as imagens à próxima mensagem do LLM; caso contrário, exibe um aviso
- Envia o resultado da ferramenta de volta para o Ollama
- Se estiver no Modo Agente, repete o processo se o modelo solicitar mais chamadas de ferramenta
Finalmente, o cliente:
- Exibe a resposta final do modelo incorporando os resultados das ferramentas

Modo Agente

Alguns modelos podem solicitar múltiplas chamadas de ferramenta em uma única conversa. O cliente suporta um Modo Agente que permite execução iterativa de ferramentas:

Quando o modelo solicita uma chamada de ferramenta, o cliente a executa e envia o resultado de volta para o modelo
Esse processo se repete até que o modelo forneça uma resposta final ou atinja o limite de iterações configurado
Você pode definir o número máximo de iterações usando o comando /loop-limit (/ll)
O limite padrão de loop é 7 para evitar loops infinitos

Quando o limite de loop é atingido

Em vez de parar silenciosamente, o cliente pausa e pergunta como você deseja prosseguir:

Escolha	Tecla	Descrição
Continuar	`c` (padrão)	Concede outro lote de iterações (mesmo tamanho do limite atual)
Número	`n`	Escolha exatamente quantas iterações adicionais permitir
Ilimitado	`u`	Remove o limite e executa até o modelo parar de solicitar ferramentas
Encerrar	`w`	Pede ao modelo para resumir o que coletou até agora e produzir uma resposta final — preserva todos os resultados de ferramentas coletados antes do limite
Abortar	`a`	Descarta a rodada inteira (nada é salvo no histórico)

[!NOTE] Se você quiser evitar o uso do Modo Agente, basta definir o limite de loop para 1.

Demonstração Rápida do Modo Agente:

Comandos Interativos

Durante o chat, use estes comandos:

[!IMPORTANT] NOVO: Comandos interativos integrados agora exigem um / inicial.

Use /help, /model, /tools, /prompts, etc.

Nomes de comandos simples como help ou model não são mais executados como comandos.

Invocações de prompt também usam /, com /server:prompt_name recomendado para evitar colisões.

ollmcp main interface

Comando	Atalho	Descrição
`abort`	`a`	Enquanto o modelo está gerando, aborta a geração da resposta atual
`/clear`, `/new`	`/cc`	Limpa o histórico da conversa e o contexto
`/cls`	`/clear-screen`	Limpa a tela do terminal
`/context`	`/c`	Alterna a retenção de contexto
`/context-info`	`/ci`	Exibe estatísticas de contexto
`/export-history`	`/eh`	Exporta o histórico do chat para um arquivo JSON
`/full-history`	`/fh`	Exibe todo o histórico da conversa
`/help`	`/h`	Exibe ajuda e comandos disponíveis
`/import-history`	`/ih`	Importa o histórico do chat de um arquivo JSON
`/human-in-the-loop`	`/hil`	Alterna confirmações Human-in-the-Loop para execução de ferramentas
`/load-config`	`/lc`	Carrega configuração de ferramentas e modelo de um arquivo
`/loop-limit`	`/ll`	Define o máximo de iterações do loop de ferramentas (Modo Agente). Padrão: 7
`/model`	`/m`	Lista e seleciona um modelo Ollama diferente
`/model-config`	`/mc`	Configura parâmetros avançados do modelo e prompt do sistema
`/display-mode`	`/dm`	Escolhe modos de exibição de resposta: Simples, Markdown, Ambos ou Markdown (blocos)
`/input-mode`	`/im`	Escolhe modo de entrada de chat de linha única ou multilinha
`/prompts`	`/pr`	Navega e visualiza todos os prompts MCP disponíveis
`/server:prompt_name`	`/prompt_name`	Invoca um prompt (qualificado é recomendado)
`/resources`	`/res`	Navega e visualiza todos os recursos MCP disponíveis
`@uri`	-	Lê um recurso específico por URI (ex.: `@server://info`)
`/quit`, `/exit`, `/bye`	`/q`, `Ctrl+C`, ou `Ctrl+D`	Sai do cliente
`/reload-servers`	`/rs`	Recarrega todos os servidores MCP com a configuração atual
`/reset-config`	`/rc`	Redefine a configuração para os padrões (todas as ferramentas ativadas)
`/save-config`	`/sc`	Salva a configuração atual de ferramentas e modelo em um arquivo
`/show-metrics`	`/sm`	Alterna a exibição de métricas de desempenho
`/show-thinking`	`/st`	Alterna a visibilidade do texto de raciocínio (visível por padrão)
`/thinking-mode`	`/tm`	Alterna o modo de raciocínio em modelos suportados
`/reasoning-effort`	`/re`	Define o nível de esforço de raciocínio (auto/minimal/low/medium/high/xhigh) quando o modo de raciocínio está ativado. Padrão: medium
`/show-tool-execution`	`/ste`	Alterna a visibilidade da exibição de execução de ferramentas
`/tools`	`/t`	Abre a interface de seleção de ferramentas

Ferramentas MCP

A interface de seleção de ferramentas e servidores permite ativar ou desativar ferramentas específicas:

ollmcp tool and server selection interface

Digite números separados por vírgulas (ex.: 1,3,5) para alternar ferramentas específicas
Digite intervalos de números (ex.: 5-8) para alternar múltiplas ferramentas consecutivas
Digite S + número (ex.: S1) para alternar todas as ferramentas de um servidor específico
a ou all - Ativa todas as ferramentas
n ou none - Desativa todas as ferramentas
d ou desc - Mostra/oculta descrições de ferramentas
j ou json - Mostra esquemas JSON detalhados das ferramentas ativadas para fins de depuração
s ou save - Salva alterações e retorna ao chat
q ou quit - Cancela alterações e retorna ao chat

Prompts MCP

Os Prompts MCP fornecem iniciadores de conversa e modelos de contexto reutilizáveis, definidos pelo servidor. Os servidores podem expor prompts com descrições, argumentos obrigatórios e mensagens pré-formatadas que ajudam você a iniciar rapidamente tipos específicos de conversas ou injetar contexto estruturado no seu chat.

Recursos

📋 Navegar por Prompts: Visualize todos os prompts disponíveis dos servidores conectados com descrições e requisitos de argumentos
⚡️ Invocação Rápida: Use sintaxe de barra para invocar prompts (/server:prompt_name recomendado)
🔤 Autocompletar: Digite / para ver sugestões de prompts com correspondência difusa
📝 Coleta de Argumentos: Prompts interativos guiam você pelos parâmetros obrigatórios
👁️ Pré-visualização: Revise o conteúdo do prompt antes da injeção para garantir que atenda às suas necessidades
🎯 Injeção Flexível: Escolha executar imediatamente ou apenas injetar (adicionar ao histórico sem acionar o modelo)
🧠 Consciente do Contexto: Adapta automaticamente o comportamento com base em se o prompt termina com mensagem de usuário ou assistente
🔄 Rollback Seguro: Limpeza automática do histórico se você abortar ou encontrar erros
💬 Conteúdo de Texto: Suporta mensagens de prompt baseadas em texto (suporte a imagem/áudio/recurso em breve)

Como Usar Prompts MCP

Navegar pelos Prompts Disponíveis:

/prompts  # or '/pr'

Isso exibe todos os prompts agrupados por servidor, mostrando seus nomes, argumentos obrigatórios e descrições.

Invocar um Prompt:

/server:prompt_name

Por exemplo, se um servidor chamado docs fornece um prompt "summarize":

/docs:summarize

Se um nome de prompt for único entre os servidores conectados, você pode usar a forma abreviada:

/summarize

Se vários servidores expõem o mesmo nome de prompt, o cliente pedirá que você use a forma qualificada e sugerirá opções válidas de /server:prompt_name.

Autocompletar:

Digite / para ver todos os prompts disponíveis com descrições
Continue digitando para filtrar prompts com correspondência difusa
Use as setas do teclado para navegar e pressione Enter para selecionar

[!TIP] Os prompts são descobertos automaticamente quando você se conecta aos servidores MCP. Se um servidor suportar prompts, eles estarão disponíveis imediatamente na lista prompts e no autocompletar.

Fluxo de Trabalho:

Digite /server:prompt_name (recomendado) ou selecione no autocompletar
Se o prompt exigir argumentos, você será solicitado a fornecê-los
Revise a pré-visualização do prompt mostrando o que será injetado
Escolha como usar o prompt:
- y/yes (padrão): Envia o prompt para o modelo e obtém uma resposta
  - Para prompts que terminam com uma mensagem de usuário: Usa essa mensagem como consulta
  - Para prompts que terminam com uma mensagem de assistente: Adiciona "Por favor, responda com base no contexto acima." como consulta
- i/inject: Apenas adiciona o prompt ao histórico da conversa sem acionar o modelo (permite que você digite sua própria consulta depois)
- n/no: Cancela e retorna ao chat
O prompt é injetado com base na sua escolha
Se você abortar durante a geração do modelo (pressione 'a'), as alterações são revertidas automaticamente

Exemplo: ollmcp prompt feature screenshot

[!WARNING] Limitações de Tipos de Conteúdo: Os Prompts MCP atualmente suportam apenas conteúdo de texto. Os seguintes tipos de conteúdo ainda não são suportados e serão ignorados automaticamente:

🖼️ Imagens - Conteúdo de imagem em prompts

🎵 Áudio - Conteúdo de áudio em prompts

📦 Recursos - Conteúdo de recurso incorporado

Recursos MCP

Os Recursos MCP fornecem acesso a dados contextuais expostos pelos servidores MCP — arquivos, documentos, dados estruturados e muito mais. Os servidores podem expor recursos com metadados (nome, descrição, tipo MIME) que você pode navegar e ler no contexto da sua conversa.

Recursos

📋 Navegar por Recursos: Visualize todos os recursos disponíveis dos servidores conectados com URIs, nomes, tipos MIME e descrições
📖 Ler Recursos: Use a sintaxe @uri para ler o conteúdo do recurso, de forma independente ou inline dentro de uma consulta
📝 Conteúdo de Texto: Suporte completo para recursos baseados em texto (markdown, código, logs, etc.)
🖼️ Suporte a Imagens para Visão: Recursos de imagem (image/*) são automaticamente encaminhados como imagens base64 para modelos com capacidade de visão
🎯 Injeção de Contexto: O conteúdo do recurso é armazenado em buffer e injetado como contexto junto com sua próxima consulta
🔍 Autocompletar: Digite @ para ver sugestões de recursos e modelos disponíveis com correspondência difusa
🛡️ Segurança Binária: Conteúdo binário que não é imagem (áudio, vídeo, PDFs, arquivos compactados) é detectado e ignorado graciosamente com mensagens informativas

Como Usar Recursos MCP

Navegar pelos Recursos Disponíveis:

/resources  # or '/res'

Isso exibe todos os recursos e modelos agrupados por servidor, mostrando URIs, nomes, tipos MIME e descrições. Recursos binários são marcados com uma tag [binary] e modelos com uma tag [template].

Ler um Recurso:

@<uri>

Por exemplo, para ler um recurso de arquivo:

@file:///path/to/document.md

Existem duas maneiras de usar @uri:

1. Autônomo (buffer e depois consulta): Digite @uri sozinho. O recurso é buscado e armazenado em buffer. Em seguida, digite sua consulta no próximo prompt. O conteúdo do recurso é injetado como contexto automaticamente.

2. Em linha (turno único): Inclua @uri em qualquer lugar dentro do texto da sua consulta. O recurso é buscado e a consulta é processada imediatamente em uma única etapa.

Exemplo autônomo:

qwen3/show-thinking/6-tools❯ @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.

1 resource(s) buffered. Type your query, or include @another_uri inline.

qwen3/show-thinking/6-tools❯ Next question here

Exemplo em linha:

qwen3/show-thinking/6-tools❯ summarize the key features from @server://info
✅ Read resource 'get_server_info' (197 chars)

Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.
[model response]

[!TIP] Os recursos são descobertos automaticamente quando você se conecta aos servidores MCP. Se um servidor suportar recursos, eles estarão disponíveis imediatamente na lista resources e no autocompletar @.

[!NOTE] 🖼️ Imagens (image/*) são suportadas; elas são passadas diretamente para modelos com capacidade de visão como dados base64. Conteúdo Binário: Os seguintes tipos de recurso não são suportados como contexto e serão ignorados com uma mensagem informativa:

🎵 Áudio - tipos MIME audio/*

📹 Vídeo - tipos MIME video/*

📄 PDFs - application/pdf

🗜️ Arquivos compactados - application/zip, application/octet-stream

Modos de Exibição de Resposta

O comando /display-mode (/dm) permite que você escolha como as respostas do modelo são exibidas enquanto são transmitidas:

Simples: Transmite a resposta uma vez como texto simples, sem nova renderização de markdown no final
✨NOVO Markdown (padrão): Transmite markdown formatado linha por linha — linhas acima de uma pequena cauda ao vivo são impressas uma vez e nunca redesenhadas, portanto permanece confiável mesmo com emojis ou redimensionamento de terminal
Ambos: Transmite texto simples primeiro e depois renderiza a resposta concluída novamente como markdown
Markdown (blocos): Renderiza a resposta como markdown um bloco por vez, somente anexação — cada parágrafo/lista/tabela/bloco de código é impresso uma vez quando concluído e nunca é redesenhado, portanto não pode duplicar linhas

Use /display-mode ou /dm durante o chat para abrir o seletor interativo.

Por que você pode alternar os modos:

Simples é a opção menos ruidosa se você quiser redesenho ou oscilação mínimos
Markdown combina transmissão linha por linha com formatação markdown coerente; no máximo as últimas linhas são redesenhadas, portanto as falhas permanecem limitadas mesmo com emojis ou redimensionamentos
Ambos oferece feedback rápido de transmissão mais uma renderização final limpa em markdown
Markdown (blocos) é a maneira mais conservadora de ver markdown formatado durante a transmissão, ao custo de atualizações bloco por bloco (em vez de linha por linha)

[!TIP] O modo de exibição selecionado é salvo com /save-config e restaurado com /load-config, para que você possa manter diferentes preferências de visualização para diferentes fluxos de trabalho.

Modo de Entrada

O comando /input-mode (/im) controla como você escreve mensagens de chat:

Linha única (padrão): Pressione Enter para enviar imediatamente após digitar sua mensagem
Multilinha: Pressione Enter para adicionar uma nova linha e, em seguida, pressione Esc seguido de Enter para enviar a mensagem inteira quando terminar. Isso permite mensagens mais complexas com vários parágrafos ou blocos de código.
Ctrl+J também insere uma nova linha no modo multilinha como uma alternativa confiável entre terminais

Use /input-mode ou /im durante o chat para abrir o seletor interativo.

[!IMPORTANT] Os atalhos de envio multilinha podem variar de acordo com o emulador de terminal e o tratamento do teclado do SO. Este cliente depende de Esc seguido de Enter como o atalho de envio portátil no modo multilinha. Shift+Enter e Meta+Enter podem funcionar em alguns terminais, mas não são garantidos.

Seleção de Modelo

A interface de seleção de modelo mostra todos os modelos disponíveis na sua instalação do Ollama:

ollmcp model selection interface

Digite o número do modelo que deseja usar
s ou save - Salvar a seleção do modelo e retornar ao chat
q ou quit - Cancelar a seleção do modelo e retornar ao chat

Configuração Avançada do Modelo

O comando /model-config (/mc) abre a interface de configurações avançadas do modelo, permitindo ajustar como o modelo gera respostas:

ollmcp model configuration interface

Prompt do Sistema

Prompt do Sistema: Defina o papel e o comportamento do modelo para orientar as respostas.

Parâmetros Principais

Janela de Contexto (num_ctx): Defina quanto histórico de chat o modelo usa. Equilibre com uso de memória e desempenho.
Manter Tokens: Evite que tokens importantes sejam descartados
Máximo de Tokens: Limite o comprimento da resposta (0 = automático)
Semente: Torne as saídas reproduzíveis (defina -1 para aleatório)
Temperatura: Controle a aleatoriedade (0 = determinístico, maior = criativo)
Top K / Top P / Min P / Typical P: Controles de amostragem para diversidade
Repetir Últimos N / Penalidade de Repetição: Reduza a repetição
Penalidade de Presença/Frequência: Incentive novos tópicos, reduza repetições
Sequências de Parada: Pontos de parada personalizados (até 8)
Tamanho do Lote (num_batch): Controla o agrupamento interno de solicitações; valores maiores podem aumentar a taxa de transferência, mas usam mais memória.

Comandos

Digite os números dos parâmetros 1-15 para editar as configurações
Digite sp para editar o prompt do sistema
Use u1, u2, etc. para desdefinir parâmetros, ou uall para redefinir todos
h/help: Mostrar detalhes e dicas dos parâmetros
undo: Reverter alterações
s/save: Aplicar alterações
q/quit: Cancelar

Exemplos de Configuração

Factual: temperature: 0.0-0.3, top_p: 0.1-0.5, seed: 42
Criativo: temperature: 1.0+, top_p: 0.95, presence_penalty: 0.2
Reduzir Repetições: repeat_penalty: 1.1-1.3, presence_penalty: 0.2, frequency_penalty: 0.3
Equilibrado: temperature: 0.7, top_p: 0.9, typical_p: 0.7
Reproduzível: seed: 42, temperature: 0.0
Contexto Grande: num_ctx: 8192 ou maior para conversas complexas que exigem mais contexto

[!TIP] Todos os parâmetros são padronizados como não definidos, permitindo que o Ollama use seus próprios valores otimizados. Use help no menu de configuração para obter detalhes e recomendações. As alterações são salvas com sua configuração.

Modo de Pensamento e Esforço de Raciocínio

Ative o modo de pensamento com /thinking-mode (/tm) para ativar o raciocínio estendido em modelos suportados (por exemplo, qwen3, deepseek-r1, Claude com pensamento estendido). Use /show-thinking (/st) para alternar se o processo de raciocínio é visível na resposta.

Use /reasoning-effort (/re) para controlar quanto esforço de raciocínio o modelo aplica quando o modo de pensamento está ativado:

Nível	Descrição
`auto`	Esforço padrão do provedor (recomendado para nuvem)
`minimal`	Mais rápido, menos raciocínio
`low`	Raciocínio leve
`medium`	Equilibrado — padrão
`high`	Raciocínio mais completo
`xhigh`	Esforço máximo de raciocínio

[!NOTE] Alguns provedores ou modelos podem ignorar as configurações de esforço de raciocínio.

Recarregamento de Servidor para Desenvolvimento

O comando /reload-servers (/rs) é particularmente útil durante o desenvolvimento de servidores MCP. Ele permite recarregar todos os servidores conectados sem reiniciar todo o aplicativo cliente.

Principais Benefícios:

🔄 Recarga Quente: Aplique instantaneamente alterações ao código do seu servidor MCP
🛠️ Fluxo de Trabalho de Desenvolvimento: Perfeito para desenvolvimento iterativo e testes
📝 Atualizações de Configuração: Captura automaticamente alterações nas configurações JSON do servidor ou nas configurações do Claude
🎯 Preservação de Estado: Mantém suas preferências de ferramentas ativadas/desativadas entre recargas
⚡️ Economia de Tempo: Não é necessário reiniciar o cliente e reconfigurar tudo

Quando Usar:

Após modificar a implementação do seu servidor MCP
Quando você atualizou as configurações do servidor em arquivos JSON
Após alterar a configuração MCP do Claude
Durante a depuração para garantir que você está testando a versão mais recente do servidor

Basta digitar /reload-servers ou /rs na interface de chat, e o cliente irá:

Desconectar de todos os servidores MCP atuais
Reconectar usando os mesmos parâmetros (servidores adicionados via ollmcp mcp add, caminhos de servidor, arquivos de configuração, --claude-desktop)
Restaurar suas configurações anteriores de ferramentas ativadas/desativadas
Exibir o status atualizado do servidor e das ferramentas

Esse recurso melhora drasticamente a experiência de desenvolvimento ao criar e testar servidores MCP.

Execução de Ferramentas com Intervenção Humana (HIL)

O recurso de Intervenção Humana fornece uma camada adicional de segurança, permitindo que você revise e aprove as execuções de ferramentas antes que elas sejam executadas. Isso é particularmente útil para:

🛡️ Segurança: Revise operações potencialmente destrutivas antes da execução
🔍 Aprendizado: Entenda quais ferramentas o modelo deseja usar e por quê
🎯 Controle: Execução seletiva apenas das ferramentas que você aprovar
🚫 Prevenção: Impedir que chamadas de ferramentas indesejadas sejam executadas
🔄 Modo de Sessão: Aprovar automaticamente todas as ferramentas para a sessão de consulta atual
🛑 Abortar Consulta: Abortar toda a consulta sem salvar no histórico

Exibição de Confirmação HIL

Quando o HIL está ativado, você verá um prompt de confirmação antes de cada execução de ferramenta:

Exemplo:

ollmcp HIL confirmation screenshot

Opções de Confirmação HIL

Quando solicitado, você pode escolher entre as seguintes opções:

y/yes: Executar esta chamada de ferramenta específica
n/no: Pular esta chamada de ferramenta e continuar com a consulta
s/session: Executar esta e todas as chamadas de ferramenta subsequentes para a consulta atual sem prompts adicionais
d/disable: Desativar permanentemente as confirmações HIL (pode ser reativado com o comando /hil)
a/abort: Abortar toda a consulta imediatamente sem salvar no histórico

[!TIP] A opção sessão é particularmente útil quando o modelo precisa executar várias ferramentas em sequência. Em vez de confirmar cada uma individualmente, você pode aprovar todas as ferramentas para a sessão de consulta atual; em seguida, o HIL será redefinido automaticamente para a próxima consulta.

Configuração de Intervenção Humana (HIL)

Estado Padrão: As confirmações HIL estão ativadas por padrão por segurança
Comando de Alternância: Use /human-in-the-loop ou /hil para ativar/desativar
Configurações Persistentes: A preferência HIL é salva com sua configuração
Desativação Rápida: Escolha "disable" durante qualquer confirmação para desativar permanentemente
Aprovação Automática de Sessão: Use "session" durante a confirmação para aprovar todas as ferramentas para a consulta atual
Abortar Consulta: Use "abort" durante a confirmação para interromper imediatamente a consulta sem salvar
Reativação: Use o comando /hil a qualquer momento para reativar as confirmações

Benefícios:

Segurança Aprimorada: Evite execuções acidentais ou indesejadas de ferramentas
Conscientização: Entenda quais ações o modelo está tentando executar
Controle Seletivo: Escolha quais operações permitir caso a caso
Fluxo de Trabalho Flexível: Modo de sessão para consultas eficientes com várias ferramentas, aprovação individual para operações sensíveis
Abortar Limpo: Interrompa consultas problemáticas imediatamente sem poluir o histórico da conversa
Tranquilidade: Visibilidade e controle totais sobre ações automatizadas

Métricas de Desempenho

O recurso de Métricas de Desempenho exibe dados detalhados de desempenho do modelo após cada consulta em um painel com bordas. As métricas mostram durações, contagens de tokens e taxas de geração diretamente da resposta do Ollama. Métricas Exibidas:

total duration: Tempo total gasto gerando a resposta completa (segundos)
load duration: Tempo gasto carregando o modelo (milissegundos)
prompt eval count: Número de tokens no prompt de entrada
prompt eval duration: Tempo gasto avaliando o prompt de entrada (milissegundos)
eval count: Número de tokens gerados na resposta
eval duration: Tempo gasto gerando os tokens da resposta (segundos)
prompt eval rate: Velocidade de processamento do prompt de entrada (tokens/segundo)
eval rate: Velocidade de geração dos tokens da resposta (tokens/segundo)

Exemplo: ollmcp ollama performance metrics screenshot

Configuração de Métricas de Desempenho

Estado Padrão: As métricas estão desabilitadas por padrão para uma saída mais limpa
Comando de Alternância: Use /show-metrics ou /sm para habilitar/desabilitar a exibição de métricas
Configurações Persistentes: A preferência de métricas é salva com sua configuração

Benefícios:

Monitoramento de Desempenho: Acompanhe a eficiência do modelo e os tempos de resposta
Rastreamento de Tokens: Monitore o consumo real de tokens para análise
Benchmarking: Compare o desempenho entre diferentes modelos

[!NOTE] Fonte de Dados: Todas as métricas vêm diretamente da resposta do Ollama, garantindo precisão e confiabilidade.

Gerenciamento de Histórico

O recurso de Gerenciamento de Histórico permite visualizar, exportar e importar seu histórico de conversas. Isso é útil para:

📜 Visualização Completa do Histórico: Revise todas as conversas da sua sessão atual
💾 Exportar: Salve conversas em arquivos JSON para backup ou análise
📥 Importar: Carregue o histórico de conversas anterior para continuar de onde parou
🔄 Portabilidade: Compartilhe ou transfira conversas entre sessões

Comandos de Histórico

Visualizar Histórico Completo:

/full-history  # or '/fh'

Exibe todo o histórico de conversas da sessão atual em uma visualização formatada, mostrando tanto consultas quanto respostas.

Exportar Histórico:

/export-history  # or '/eh'

Exporta seu histórico de chat atual para um arquivo JSON. Você pode especificar um nome de arquivo personalizado ou usar o nome padrão baseado em timestamp (por exemplo, ollmcp_chat_history_2026-01-05_143022.json). Os arquivos são salvos no diretório ~/.config/ollmcp/history/. O comando inclui proteção contra sobrescrita de arquivos.

Importar Histórico:

/import-history  # or '/ih'

Importa um histórico de chat exportado anteriormente de um arquivo JSON. O comando valida a estrutura JSON para garantir compatibilidade. O histórico importado é adicionado ao seu contexto de conversa atual.

Armazenamento de Histórico:

Local de exportação: ~/.config/ollmcp/history/
Formato de nome de arquivo padrão: ollmcp_chat_history_YYYY-MM-DD_HHMMSS.json
O formato JSON inclui tanto consultas quanto respostas com validação adequada da estrutura

Benefícios:

Continuidade de Sessão: Retome conversas em diferentes sessões
Backup: Mantenha registros de conversas importantes
Análise: Exporte o histórico para análise ou revisão externa
Compartilhamento: Compartilhe o contexto da conversa com membros da equipe
Testes: Importe conversas de teste para desenvolvimento e depuração

[!TIP] Ao exportar, se você não fornecer um nome de arquivo, o sistema gera automaticamente um nome de arquivo com timestamp para evitar sobrescritas acidentais.

Recursos de Autocompletar e Prompt

Autocompletar do Shell Typer

A CLI suporta autocompletar do shell para todas as opções e argumentos via Typer
Para habilitar, execute ollmcp --install-completion e siga as instruções para o seu shell
Aproveite o autocompletar por tabulação para todas as opções agrupadas e gerais

Autocompletar estilo FZF

Autocompletar por namespace com barra para comandos e prompts (/)
Descrições de comandos mostradas no menu
Correspondência sem diferenciar maiúsculas de minúsculas para conveniência
Lista de comandos centralizada para consistência
A digitação de consultas em texto simples é intencionalmente livre de ruído de autocompletar de ações

Autocompletar de Prompts MCP

Digite / para acionar o autocompletar de prompts
Correspondência difusa em nomes e descrições de prompts
Suporta referências de prompt qualificadas como /server:prompt_name
Mostra descrições de prompts no menu
Os argumentos do prompt são coletados durante a invocação do prompt (não mostrados nas linhas de autocompletar)
Truncamento de descrição ciente da largura do terminal

Prompt Contextual

O prompt de chat agora fornece informações contextuais claras de relance:

Modelo: Mostra o modelo Ollama atual em uso
Modo de Pensamento: Indica se o "modo de pensamento" está ativo (para modelos suportados)
Ferramentas: Exibe o número de ferramentas habilitadas

Exemplo de prompt:

qwen3/show-thinking/12-tools❯

qwen3 Nome do modelo
/show-thinking Indicador do modo de pensamento (se habilitado, caso contrário /thinking ou omitido)
/12-tools Número de ferramentas habilitadas (ou /1-tool para singular)
❯ Símbolo do prompt

Isso facilita ver seu contexto atual antes de inserir uma consulta.

[!TIP] Digite / após o símbolo do prompt para ver sugestões de autocompletar para prompts MCP disponíveis.

Gerenciamento de Configuração

[!TIP] Executar ollmcp sem flags carrega automaticamente a configuração padrão de ~/.config/ollmcp/config.json se ela existir.

O cliente salva e carrega suas preferências entre sessões:

Ao usar /save-config, você pode fornecer um nome para a configuração ou usar o padrão
As configurações são armazenadas no diretório ~/.config/ollmcp/
A configuração padrão é salva como ~/.config/ollmcp/config.json
Configurações nomeadas são salvas como ~/.config/ollmcp/{name}.json

Perfis por provedor

As configurações de conexão são armazenadas por provedor, portanto, alternar provedores nunca reutiliza o modelo, host ou chave de API de outro provedor. Cada provedor mantém seus próprios:

Seleção de Modelo
Host / URL base da API
Chave de API

A configuração também registra um defaultProvider. Quando você executa ollmcp sem a flag --provider, ele carrega o perfil desse provedor; uma instalação nova começa em ollama. Cada vez que você /save-config, o provedor que você está usando atualmente torna-se o novo padrão, então executar ollmcp simples retoma de onde você parou. Passe --provider <name> a qualquer momento para alternar para (e carregar) o perfil de um provedor diferente, e --model / --host / --api-key substituem os valores salvos para essa execução.

[!NOTE] Apenas uma chave passada com --api-key é armazenada, em texto simples, em ~/.config/ollmcp/config.json. Chaves fornecidas através da variável de ambiente $OLLMCP_API_KEY ou da variável de ambiente nativa de um provedor (por exemplo, OPENROUTER_API_KEY) nunca são gravadas em disco; use uma delas se você não quiser que sua chave seja persistida.

As seguintes configurações são compartilhadas entre todos os provedores:

Parâmetros avançados do modelo (prompt do sistema, temperatura, configurações de amostragem, etc.)
Status habilitado/desabilitado de todas as ferramentas
Configurações de retenção de contexto
Configurações do modo de pensamento
Preferência do modo de exibição de respostas
Preferências de exibição de execução de ferramentas
Preferências de exibição de métricas de desempenho
Configurações de confirmação Human-in-the-Loop

Exemplo ~/.config/ollmcp/config.json:

{
  "defaultProvider": "openai",
  "providers": {
    "ollama": { "host": "http://localhost:11434", "model": "qwen3:1.7b", "apiKey": "" },
    "openai": { "host": "", "model": "gpt-5.5", "apiKey": "sk-..." }
  },
  "enabledTools": {},
  "modelConfig": {},
  "...": "shared settings"
}

[!TIP] Arquivos de configuração planos mais antigos (com host/model/provider/apiKey de nível superior) são migrados automaticamente na primeira vez que você executa esta versão e reescritos no formato por provedor no seu próximo /save-config.

Formato de Configuração do Servidor

O arquivo de configuração JSON suporta tipos de servidor STDIO, SSE e Streamable HTTP (MCP 1.10.1):

{
  "mcpServers": {
    "stdio-server": {
      "command": "command-to-run",
      "args": ["arg1", "arg2", "..."],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "disabled": false
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer your-token-here"
      },
      "disabled": true
    },
    "http-server": {
      "type": "streamable_http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-api-key-here"
      },
      "disabled": false
    }
  }
}

[!NOTE] Suporte de Transporte MCP 1.10.1: O cliente agora suporta o transporte Streamable HTTP mais recente com desempenho e confiabilidade aprimorados. Se você especificar uma URL sem um tipo, o cliente usará por padrão o transporte Streamable HTTP.

Dicas: onde colocar as configurações do servidor MCP e um exemplo funcional

Um ponto comum de confusão é onde armazenar os arquivos de configuração do servidor MCP e como o recurso de salvar/carregar da TUI é usado. Aqui está um guia prático e curto que ajudou outros usuários:

Os comandos /save-config / /load-config (ou /sc / /lc) da TUI destinam-se a salvar preferências da TUI, como quais ferramentas você habilitou, seu modelo selecionado, modo de pensamento, modo de exibição e outras configurações do lado do cliente. Eles não são necessários para registrar conexões de servidor MCP com o cliente.
Para arquivos JSON do servidor MCP (o objeto mcpServers mostrado acima), recomendamos mantê-los fora do diretório de configuração da TUI ou em uma subpasta clara, por exemplo:

~/.config/ollmcp/mcp-servers/config.json

Você pode então apontar ollmcp para esse arquivo na inicialização com -j / --servers-json.

[!IMPORTANT] Para servidores MCP baseados em HTTP, "type": "http", "streamable-http" e "streamable_http" são todos aceitos e tratados da mesma forma. Verifique também a seção Caminhos de endpoint MCP comuns abaixo para endpoints típicos.

Aqui está um exemplo funcional mínimo, digamos que este é o seu ~/.config/ollmcp/mcp-servers/config.json:

{
  "mcpServers": {
    "github": {
      "type": "streamable_http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer mytoken"
      }
    }
  }
}

[!TIP] Ao usar o servidor MCP do GitHub, certifique-se de substituir "mytoken" pelo seu token real da API do GitHub.

Com esse arquivo no lugar, você pode conectar usando:

ollmcp -j ~/.config/ollmcp/mcp-servers/config.json

Aqui você pode encontrar um problema do GitHub relacionado a essa armadilha comum: https://github.com/jonigl/mcp-client-for-ollama/issues/112#issuecomment-3446569030

Demonstração

Uma demonstração curta (asciicast) que deve ajudar qualquer pessoa a reproduzir a configuração funcional rapidamente. Este exemplo usa um exemplo de servidor MCP com protocolo HTTP streamable:

Caminhos de endpoint MCP comuns

Servidores MCP Streamable HTTP normalmente expõem o endpoint MCP em /mcp (por exemplo, https://host/mcp), enquanto servidores SSE comumente usam /sse (por exemplo, https://host/sse). Abaixo está um trecho da especificação MCP (2025-06-18):

O servidor DEVE fornecer um único caminho de endpoint HTTP (doravante referido como endpoint MCP) que suporte ambos os métodos POST e GET. Por exemplo, isso poderia ser uma URL como https://example.com/mcp.

Você pode encontrar mais detalhes na especificação MCP versão 2025-06-18 - Transports.

[!NOTE] Os certificados HTTPS para servidores MCP remotos são verificados em relação ao armazenamento de confiança do seu sistema operacional, não ao pacote certifi. Se um servidor MCP estiver atrás de uma CA privada ou corporativa, ou se você executar ollmcp em um contêiner mínimo sem armazenamento de CA do sistema, o handshake TLS falha com um erro que não menciona ollmcp. Aponte SSL_CERT_FILE (um arquivo de pacote) ou SSL_CERT_DIR (um diretório) para sua CA para corrigir:
export SSL_CERT_FILE=/path/to/corporate-ca.pem

Modelos Compatíveis

Os seguintes modelos Ollama funcionam bem com uso de ferramentas:

gemma4
qwen3.5
lfm2.5-thinking
llama3.2
mistral

Para uma lista completa de modelos Ollama com capacidades de uso de ferramentas, visite a página oficial de modelos Ollama.

Para modelos que também podem processar imagens retornadas por ferramentas, consulte a página de modelos de visão Ollama.

Modelos Ollama Cloud

MCP Client for Ollama agora suporta modelos Ollama Cloud, permitindo que você use modelos poderosos hospedados na nuvem com capacidades de chamada de ferramentas enquanto aproveita suas ferramentas MCP locais. Modelos de nuvem podem ser executados sem uma GPU local poderosa, tornando possível acessar modelos maiores que não caberiam em um computador pessoal.

Modelos Ollama Cloud suportados incluem, por exemplo:

gpt-oss:20b-cloud
gpt-oss:120b-cloud
deepseek-v3.1:671b-cloud
qwen3-coder:480b-cloud

Para usar modelos Ollama Cloud com este cliente:

Primeiro, baixe o modelo de nuvem:
```
ollama pull gpt-oss:120b-cloud
```
Execute o cliente com o modelo de nuvem escolhido:
```
ollmcp --model gpt-oss:120b-cloud
```

[!NOTE] O modelo deepseek-v3.1:671b-cloud só suporta uso de ferramentas quando o modo de pensamento está desativado. Você pode alternar o modo de pensamento em ollmcp digitando /thinking-mode ou /tm.

Para mais informações sobre Ollama Cloud, visite a documentação do Ollama Cloud.

Patrocinadores

Este projeto é apoiado por:

Atlas Cloud

Atlas Cloud é uma plataforma de inferência de IA multimodal — uma única API de IA com acesso unificado a mais de 300 modelos selecionados para cargas de trabalho de vídeo, imagem e LLM.

Ela funciona com o ollmcp prontamente:

ollmcp --provider atlascloud --api-key YOUR_ATLASCLOUD_API_KEY
# or export the key once and skip the flag:
export ATLASCLOUD_API_KEY=YOUR_ATLASCLOUD_API_KEY
ollmcp --provider atlascloud

Streaming e chamada de ferramentas são totalmente suportados, e você pode navegar e escolher qualquer um dos modelos do Atlas Cloud com o comando interativo /model.

Torne-se um patrocinador

Quer ver seu logotipo aqui? Apoie o projeto via GitHub Sponsors ❤️

Onde Posso Encontrar Mais Servidores MCP?

Você pode explorar uma coleção de servidores MCP no repositório oficial de Servidores MCP.

Este repositório contém implementações de referência para o Model Context Protocol, servidores construídos pela comunidade e recursos adicionais para aprimorar suas capacidades de ferramentas de LLM.

Projetos Relacionados

Ollama MCP Bridge - Uma camada de API em Python que fica na frente do Ollama, adicionando automaticamente ferramentas de vários servidores MCP a cada solicitação de chat. Este projeto fornece uma solução de proxy transparente que pré-carrega todos os servidores MCP na inicialização e integra perfeitamente suas ferramentas à API do Ollama.
Exemplo de Servidor MCP com HTTP Streamable - Um exemplo de servidor MCP demonstrando o uso do protocolo HTTP streamable.

Segurança

Os servidores MCP aos quais você se conecta são confiáveis por você, e suas respostas de ferramentas/recursos são tratadas como conteúdo não confiável que chega ao modelo. Consulte SECURITY.md para o modelo de confiança, como a injeção indireta de prompt é tratada e como relatar uma vulnerabilidade.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Ollama pelo runtime local de LLM
Model Context Protocol pela especificação e exemplos
any-llm pela interface única para múltiplos provedores de LLM
Rich pela interface de terminal
Typer pela experiência moderna de CLI
Prompt Toolkit pela interface de linha de comando interativa
uv pelo gerenciador de pacotes Python extremamente rápido e gerenciamento de ambientes virtuais
Asciinema pela gravação de demonstração

Feito com ❤️ por jonigl

MCP Client for Ollama

Documentação

MCP Client for Ollama (ollmcp)

Sumário

Visão Geral

Recursos

Requisitos

Início Rápido

Opções de Instalação

Solução de Problemas

Could not find a version that satisfies the requirement ollmcp (from versions: none)

error: externally-managed-environment (PEP 668)

Gerenciando Servidores MCP via CLI

Opções do mcp add

Escopos

Argumentos de Linha de Comando

Configuração do Servidor MCP:

Configuração do Provedor de Inferência:

Opções Gerais:

Registro de Log do Servidor MCP:

Provedores de Inferência Suportados

Ordem de resolução da chave de API

Exemplos de Uso

Como Funcionam as Chamadas de Ferramentas

Modo Agente

Quando o limite de loop é atingido

Demonstração Rápida do Modo Agente:

Comandos Interativos

Ferramentas MCP

Prompts MCP

Recursos

Como Usar Prompts MCP

Recursos MCP

Recursos

Como Usar Recursos MCP

Modos de Exibição de Resposta

Modo de Entrada

Seleção de Modelo

Configuração Avançada do Modelo

Prompt do Sistema

Parâmetros Principais

Comandos

Exemplos de Configuração

Modo de Pensamento e Esforço de Raciocínio

Recarregamento de Servidor para Desenvolvimento

Execução de Ferramentas com Intervenção Humana (HIL)

Exibição de Confirmação HIL

Opções de Confirmação HIL

Configuração de Intervenção Humana (HIL)

Métricas de Desempenho

Configuração de Métricas de Desempenho

Gerenciamento de Histórico

Comandos de Histórico

Recursos de Autocompletar e Prompt

Autocompletar do Shell Typer

Autocompletar estilo FZF

Autocompletar de Prompts MCP

Prompt Contextual

Gerenciamento de Configuração

Perfis por provedor

Formato de Configuração do Servidor

Dicas: onde colocar as configurações do servidor MCP e um exemplo funcional

Demonstração

Caminhos de endpoint MCP comuns

Modelos Compatíveis

Modelos Ollama Cloud

Patrocinadores

Atlas Cloud

Torne-se um patrocinador

Onde Posso Encontrar Mais Servidores MCP?

Projetos Relacionados

Segurança

Licença

Agradecimentos

`Could not find a version that satisfies the requirement ollmcp (from versions: none)`

`error: externally-managed-environment` (PEP 668)