MCP Client for Ollama

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

GitHub

801

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)

PyPI - Downloads

_{Patrocinado por}

_{Saiba 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 Prático
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 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 Streamable HTTP
📋 Suporte a Prompts MCP: Navegue, invoque e gerencie prompts de servidores MCP com coleta de argumentos, pré-visualização e rollback seguro
📦 Suporte a Recursos MCP: Navegue e leia dados contextuais de servidores MCP, incluindo arquivos, documentos e dados estruturados
☁️ Suporte 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: Interface de console interativa com estilo moderno
🌊 Respostas em Streaming: Veja as saídas do modelo em tempo real enquanto são geradas
📝 Modos de Exibição de Respostas: Alterne entre visualizações de resposta Plain, Markdown, Both 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 que elas sejam executadas para maior controle e segurança
🎮 Configuração Avançada de Modelo: Ajuste fino de 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 Raciocínio: 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 para auto, minimal, low, medium, high ou xhigh 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 raciocínio 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 de 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 com o 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 padrão .mcp.json 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 registrado 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 seu 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 comuns de endpoint MCP 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: Carregar 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: Mostrar versão e sair
--help, -h: Mostrar mensagem de ajuda e sair
--install-completion: Instalar scripts de autocompletar de shell para o cliente
--show-completion: Mostrar opções de completar de shell disponíveis

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 do próprio 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 capacidades: 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 em badges, 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). Então, 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 como baixar um se nenhum estiver instalado).

Usar 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.

Usar 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

Usar 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.

Conectar 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

Conectar 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

Misturar 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

Incluir 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 ao 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 habilitado) permitindo que você revise e aprove a chamada de ferramenta
- Extrai o nome da ferramenta e os argumentos da resposta do modelo
- Chama o servidor MCP apropriado com esses argumentos (apenas se aprovado ou se HIL estiver desabilitado)
- 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 ao Ollama
- Se estiver no Modo Agente, repete o processo se o modelo solicitar mais chamadas de ferramentas
Finalmente, o cliente:
- Exibe a resposta final do modelo incorporando os resultados das ferramentas

Modo Agente

Alguns modelos podem solicitar várias chamadas de ferramentas 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 ao modelo
Esse processo se repete até que o modelo forneça uma resposta final ou atinja o limite de loop configurado
Você pode definir o número máximo de iterações usando o comando /loop-limit (/ll)
O limite de loop padrão é 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)	Conceder outro lote de iterações (mesmo tamanho do limite atual)
Número	`n`	Escolher exatamente quantas iterações adicionais permitir
Ilimitado	`u`	Remover o limite e rodar até o modelo parar de solicitar ferramentas
Encerrar	`w`	Pedir 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`	Descartar 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: Os comandos interativos integrados agora exigem um prefixo /.

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 /, sendo /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`	`/cc`	Limpa o histórico de 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 de conversa para um arquivo JSON
`/full-history`	`/fh`	Exibe todo o histórico de conversa
`/help`	`/h`	Exibe ajuda e comandos disponíveis
`/import-history`	`/ih`	Importa o histórico de conversa de um arquivo JSON
`/human-in-the-loop`	`/hil`	Alterna confirmações de 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 número 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 o prompt do sistema
`/display-mode`	`/dm`	Escolhe os modos de exibição de resposta: Plain, Markdown, Both ou Markdown (blocos)
`/input-mode`	`/im`	Escolhe o modo de entrada de chat: 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 habilitadas)
`/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á ativo. 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 habilitar ou desabilitar 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 várias ferramentas consecutivas
Digite S + número (ex.: S1) para alternar todas as ferramentas de um servidor específico
a ou all - Habilita todas as ferramentas
n ou none - Desabilita todas as ferramentas
d ou desc - Mostra/oculta descrições de ferramentas
j ou json - Mostra esquemas JSON detalhados das ferramentas habilitadas para fins de depuração
s ou save - Salva as alterações e retorna ao chat
q ou quit - Cancela as 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: Veja todos os prompts disponíveis dos servidores conectados, com descrições e requisitos de argumentos
⚡️ Invocação Rápida: Use a 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)
🧠 Ciente do Contexto: Adapta automaticamente o comportamento com base em se o prompt termina com mensagem do usuário ou do 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 o nome de um prompt for único entre os servidores conectados, você pode usar a forma curta:

/summarize

Se vários servidores expuserem 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 ao modelo e obtém uma resposta
  - Para prompts que terminam com uma mensagem do usuário: Usa essa mensagem como consulta
  - Para prompts que terminam com uma mensagem do assistente: Adiciona "Por favor, responda com base no contexto acima." como consulta
- i/inject: Apenas adiciona o prompt ao histórico de 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 por 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: Veja 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 autônoma 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 encaminhados automaticamente 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 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. Inline (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 inline:

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 escolher como as respostas do modelo são exibidas durante o streaming:

Plain: Transmite a resposta uma vez como texto simples, sem re-renderização final em markdown
✨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, então permanece confiável mesmo com emojis ou redimensionamento do terminal
Both: Transmite texto simples primeiro e depois renderiza a resposta completa 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, então não pode duplicar linhas

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

Por que você pode querer mudar de modo:

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

[!TIP] Seu 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 conforme o emulador de terminal e o tratamento do teclado do sistema operacional. 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 do histórico do 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 repetições
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 números de parâmetros 1-15 para editar configurações
Digite sp para editar o prompt do sistema
Use u1, u2, etc. para desdefinir parâmetros, ou uall para redefinir tudo
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 ficam desdefinidos por padrão, permitindo que o Ollama use seus próprios valores otimizados. Use help no menu de configuração para 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 raciocínio estendido em modelos compatíveis (por exemplo, qwen3, deepseek-r1, Claude com pensamento estendido). Use /show-thinking (/st) para alternar se o processo de raciocínio fica 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á ativo:

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 do 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 o aplicativo cliente inteiro.

Principais Benefícios:

🔄 Recarga a Quente: Aplique instantaneamente alterações no código do seu servidor MCP
🛠️ Fluxo de Desenvolvimento: Perfeito para desenvolvimento e testes iterativos
📝 Atualizações de Configuração: Detecta automaticamente alterações em configurações JSON do servidor ou configurações do Claude
🎯 Preservação de Estado: Mantém suas preferências de ferramentas habilitadas/desabilitadas 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 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 habilitadas/desabilitadas
Exibir o status atualizado do servidor e das ferramentas

Este 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 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 quer usar e por quê
🎯 Controle: Execução seletiva apenas das ferramentas que você aprovar
🚫 Prevenção: Impedir chamadas de ferramentas indesejadas de serem executadas
🔄 Modo de Sessão: Aprovar automaticamente todas as ferramentas para a sessão de consulta atual
🛑 Abortar Consulta: Abortar a consulta inteira sem salvar no histórico

Exibição de Confirmação HIL

Quando o HIL está habilitado, 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 mais prompts
d/disable: Desabilitar permanentemente as confirmações HIL (pode ser reabilitado com o comando /hil)
a/abort: Abortar a consulta inteira 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, e 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 habilitadas por padrão para segurança
Comando de Alternância: Use /human-in-the-loop ou /hil para ligar/desligar
Configurações Persistentes: A preferência HIL é salva com sua configuração
Desativação Rápida: Escolha "disable" durante qualquer confirmação para desligar permanentemente
Aprovação Automática de Sessão: Use "session" durante a confirmação para aprovar todas as ferramentas da consulta atual
Abortar Consulta: Use "abort" durante a confirmação para interromper imediatamente a consulta sem salvar
Reabilitaçã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
Consciência: 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 múltiplas ferramentas, aprovação individual para operações sensíveis
Abortamento 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 tempos de duração, 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 das 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 das 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
💾 Exportação: Salve conversas em arquivos JSON para backup ou análise
📥 Importação: Carregue 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 contexto da sua conversa atual.

Armazenamento do Histórico:

Local de exportação: ~/.config/ollmcp/history/
Formato padrão do nome de arquivo: 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 Autocomplete e Prompts

Autocompletar do Shell Typer

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

Autocomplete estilo FZF

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

Autocomplete de Prompts MCP

Digite / para acionar o autocomplete de prompts
Correspondência difusa em nomes e descrições de prompts
Suporta referências qualificadas de prompts como /server:prompt_name
Mostra descrições de prompts no menu
Os argumentos dos prompts são coletados durante a invocação do prompt (não exibidos nas linhas de autocomplete)
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 autocomplete 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, então alternar provedores nunca reutiliza o modelo, host ou chave de API de outro provedor. Cada provedor mantém seu próprio:

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 dessas 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 tipo, o cliente usará o transporte Streamable HTTP por padrão.

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

Um ponto comum de confusão é onde armazenar 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 de 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. Consulte também a seção Caminhos de endpoint MCP comuns abaixo para endpoints típicos.

Aqui está um exemplo mínimo funcional, digamos que este é 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 streamable HTTP:

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.

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, veja 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 rodar 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 seu 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 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.

Funciona com ollmcp pronto para uso:

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 da 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 LLM.

Projetos Relacionados

Ollama MCP Bridge - Uma camada de API Python que fica na frente do Ollama, adicionando automaticamente ferramentas de múltiplos 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 Ollama.
Exemplo de Servidor MCP com Streamable HTTP - Um exemplo de servidor MCP demonstrando o uso do protocolo streamable HTTP.

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 - veja o arquivo LICENSE para detalhes.

Agradecimentos

Ollama pelo runtime LLM local
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 ultrarrápido e gerenciamento de ambiente virtual
Asciinema pela gravação da 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:

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 do 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 das Métricas de Desempenho

Gerenciamento de Histórico

Comandos de Histórico

Recursos de Autocomplete e Prompts

Autocompletar do Shell Typer

Autocomplete estilo FZF

Autocomplete de Prompts MCP

Prompt Contextual

Gerenciamento de Configuração

Perfis por provedor

Formato de Configuração do Servidor

Dicas: onde colocar configurações de 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)