Ollama MCP Server

---

✨ Recursos

• ☁️ Suporte ao Ollama Cloud - Integração completa com a plataforma de nuvem do Ollama
• 🔧 14 Ferramentas Abrangentes - Acesso total à funcionalidade do SDK do Ollama
• 🔄 Arquitetura Hot-Swap - Descoberta automática de ferramentas sem configuração
• 🎯 Type-Safe - Construído com TypeScript e validação Zod
• 📊 Alta Cobertura de Testes - 96%+ de cobertura com suíte de testes abrangente
• 🚀 Zero Dependências - Pegada mínima, desempenho máximo
• 🔌 Integração Plug-and-Play - Funciona com Claude Desktop, Cline e outros clientes MCP
• 🌐 Pesquisa Web e Fetch - Pesquisa web em tempo real e extração de conteúdo via Ollama Cloud
• 🔀 Modo Híbrido - Use modelos locais e de nuvem perfeitamente em um único servidor

💡 Eleve Sua Experiência com Ollama Usando Claude Code e Desktop

O Pacote Completo: Ferramentas + Conhecimento

Este servidor MCP dá ao Claude as ferramentas para interagir com o Ollama - mas você obterá ainda mais valor instalando também a Ollama Skill do Skillsforge Marketplace:

• 🚗 Este MCP = O Carro - Todas as ferramentas e capacidades
• 🎓 Ollama Skill = Aulas de Direção - Conhecimento especializado sobre como usá-las de forma eficaz

A Ollama Skill ensina ao Claude:

• Melhores práticas para seleção e configuração de modelos
• Estratégias ideais de prompting para diferentes modelos Ollama
• Quando usar chat vs generate, embeddings e outras ferramentas
• Otimização de desempenho e solução de problemas
• Recursos avançados como chamada de ferramentas e suporte a funções

Instale ambos para a experiência completa:

1. ✅ Este servidor MCP (ferramentas)
2. ✅ Ollama Skill (expertise)

Resultado: o Claude não apenas tem o carro - ele sabe dirigir! 🏎️

📦 Instalação

Início Rápido com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"]
    }
  }
}

Instalação Global

npm install -g ollama-mcp

Para Cline (VS Code)

Adicione às suas configurações MCP do Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"]
    }
  }
}

🛠️ Ferramentas Disponíveis

Gerenciamento de Modelos

Ferramenta	Descrição
ollama_list	Lista todos os modelos locais disponíveis
ollama_show	Obtém informações detalhadas sobre um modelo específico
ollama_pull	Baixa modelos da biblioteca Ollama
ollama_push	Envia modelos para a biblioteca Ollama
ollama_copy	Cria uma cópia de um modelo existente
ollama_delete	Remove modelos do armazenamento local
ollama_create	Cria modelos personalizados a partir de Modelfile

Operações de Modelo

Ferramenta	Descrição
ollama_ps	Lista modelos atualmente em execução
ollama_generate	Gera conclusões de texto
ollama_chat	Chat interativo com modelos (suporta ferramentas/funções)
ollama_embed	Gera embeddings para texto

Ferramentas Web (Ollama Cloud)

Ferramenta	Descrição
ollama_web_search	Pesquisa na web com limites de resultados personalizáveis (requer OLLAMA_API_KEY)
ollama_web_fetch	Busca e analisa o conteúdo de páginas web (requer OLLAMA_API_KEY)

Nota: As ferramentas web exigem uma chave de API do Ollama Cloud. Elas se conectam a https://ollama.com/api para operações de pesquisa web e fetch.

⚙️ Configuração

Variáveis de Ambiente

Variável	Padrão	Descrição
OLLAMA_HOST	http://127.0.0.1:11434	Endpoint do servidor Ollama (use https://ollama.com para nuvem)
OLLAMA_API_KEY	-	Chave de API para Ollama Cloud (necessária para ferramentas web e modelos de nuvem)

Host Ollama Personalizado

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

Configuração do Ollama Cloud

Para usar a plataforma de nuvem do Ollama com recursos de pesquisa web e fetch:

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "https://ollama.com",
        "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
      }
    }
  }
}

Recursos de Nuvem:

• ☁️ Acesse modelos hospedados na nuvem
• 🔍 Pesquisa web com ollama_web_search (requer chave de API)
• 📄 Fetch web com ollama_web_fetch (requer chave de API)
• 🚀 Inferência mais rápida na infraestrutura de nuvem

Obtenha sua chave de API: Visite ollama.com para se cadastrar e obter sua chave de API.

Modo Híbrido (Local + Nuvem)

Você pode usar modelos locais e de nuvem apontando para sua instância local do Ollama enquanto fornece uma chave de API:

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "OLLAMA_API_KEY": "your-ollama-cloud-api-key"
      }
    }
  }
}

Esta configuração:

• ✅ Executa modelos locais da sua instância Ollama
• ✅ Habilita ferramentas de pesquisa web e fetch exclusivas da nuvem
• ✅ O melhor dos dois mundos: privacidade + conectividade web

🔄 Comportamento de Nova Tentativa

O servidor MCP inclui lógica inteligente de nova tentativa para lidar com falhas transitórias ao se comunicar com as APIs do Ollama:

Estratégia Automática de Nova Tentativa

Ferramentas Web (ollama_web_search e ollama_web_fetch):

• Repete automaticamente em erros de limite de taxa (HTTP 429)
• Máximo de 3 tentativas de repetição (4 solicitações no total, incluindo a inicial)
• Timeout de solicitação: 30 segundos por solicitação (evita conexões penduradas)
• Respeita o cabeçalho Retry-After quando fornecido pela API
• Usa backoff exponencial com jitter quando Retry-After não está presente

Suporte ao Cabeçalho Retry-After

O servidor lida inteligentemente com o cabeçalho HTTP padrão Retry-After em dois formatos:

1. Formato de Segundos de Atraso:

Retry-After: 60

Aguarda exatamente 60 segundos antes de repetir.

2. Formato de Data HTTP:

Retry-After: Wed, 21 Oct 2025 07:28:00 GMT

Calcula o atraso até o timestamp especificado.

Backoff Exponencial

Quando Retry-After não é fornecido ou é inválido:

• Atraso inicial: 1 segundo (padrão)
• Atraso máximo: 10 segundos (padrão, configurável)
• Estratégia: Backoff exponencial com jitter completo
• Fórmula: random(0, min(initialDelay × 2^attempt, maxDelay))

Exemplo de atrasos de repetição:

• 1ª repetição: 0-1 segundos
• 2ª repetição: 0-2 segundos
• 3ª repetição: 0-4 segundos (limitado a 0-10s no máximo)

Tratamento de Erros

Erros Repetidos (falhas transitórias):

• HTTP 429 (Too Many Requests) - limitação de taxa
• HTTP 500 (Internal Server Error) - problemas transitórios do servidor
• HTTP 502 (Bad Gateway) - gateway/proxy recebeu resposta inválida
• HTTP 503 (Service Unavailable) - servidor temporariamente incapaz de lidar com a solicitação
• HTTP 504 (Gateway Timeout) - gateway/proxy não recebeu resposta em tempo hábil

Erros Não Repetidos (falhas permanentes):

• Timeouts de solicitação (limite de 30 segundos excedido)
• Timeouts de rede (sem código de status)
• Erros de abortamento/cancelamento
• Erros HTTP 4xx (exceto 429) - erros do cliente que exigem alterações
• Outros erros HTTP 5xx (501, 505, 506, 508, etc.) - problemas de configuração/implementação

O mecanismo de repetição garante tratamento robusto de problemas temporários de API, respeitando as orientações de repetição fornecidas pelo servidor e prevenindo taxas excessivas de solicitações. Erros 5xx transitórios (500, 502, 503, 504) são seguros para repetir nas operações POST idempotentes usadas por ollama_web_search e ollama_web_fetch. Solicitações individuais expiram após 30 segundos para evitar conexões penduradas indefinidamente.

🎯 Exemplos de Uso

Chat com um Modelo

// MCP clients can invoke:
{
  "tool": "ollama_chat",
  "arguments": {
    "model": "llama3.2:latest",
    "messages": [
      { "role": "user", "content": "Explain quantum computing" }
    ]
  }
}

Gerar Embeddings

{
  "tool": "ollama_embed",
  "arguments": {
    "model": "nomic-embed-text",
    "input": ["Hello world", "Embeddings are great"]
  }
}

Pesquisa Web

{
  "tool": "ollama_web_search",
  "arguments": {
    "query": "latest AI developments",
    "max_results": 5
  }
}

🏗️ Arquitetura

Este servidor usa um padrão de autoloader hot-swap:

src/
├── index.ts          # Entry point (27 lines)
├── server.ts         # MCP server creation
├── autoloader.ts     # Dynamic tool discovery
└── tools/            # Tool implementations
    ├── chat.ts       # Each exports toolDefinition
    ├── generate.ts
    └── ...

Principais Benefícios:

• Adicione novas ferramentas colocando arquivos em src/tools/
• Nenhuma alteração de código do servidor necessária
• Cada ferramenta é testável de forma independente
• 100% de cobertura de funções em todas as ferramentas

🧪 Desenvolvimento

Pré-requisitos

• Node.js v16+
• npm ou pnpm
• Ollama em execução localmente

Configuração

# Clone repository
git clone https://github.com/rawveg/ollama-mcp.git
cd ollama-mcp

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Cobertura de Testes

Statements   : 96.37%
Branches     : 84.82%
Functions    : 100%
Lines        : 96.37%

Adicionando uma Nova Ferramenta

1. Crie src/tools/your-tool.ts:

import { ToolDefinition } from '../autoloader.js';
import { Ollama } from 'ollama';
import { ResponseFormat } from '../types.js';

export const toolDefinition: ToolDefinition = {
  name: 'ollama_your_tool',
  description: 'Your tool description',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    },
    required: ['param']
  },
  handler: async (ollama, args, format) => {
    // Implementation
    return 'result';
  }
};

2. Crie testes em tests/tools/your-tool.test.ts
3. Pronto! O autoloader a descobre automaticamente.

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, siga estas diretrizes:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Escreva testes - Mantemos cobertura de 96%+
4. Faça commit com mensagens claras (git commit -m 'Add amazing feature')
5. Envie para seu branch (git push origin feature/amazing-feature)
6. Abra um Pull Request

Padrões de Qualidade de Código

• Todas as novas ferramentas devem exportar toolDefinition
• Mantenha cobertura de testes ≥80%
• Siga os padrões TypeScript existentes
• Use schemas Zod para validação de entrada

📄 Licença

Este projeto é licenciado sob a GNU Affero General Public License v3.0 (AGPL-3.0).

Consulte LICENSE para detalhes.

🔗 Projetos Relacionados

• Skillsforge Marketplace - Skills para Claude Code, incluindo a Ollama Skill
• Ollama - Comece a usar modelos de linguagem grandes localmente
• Model Context Protocol - Padrão aberto para integração de assistentes de IA
• Claude Desktop - Aplicativo de desktop da Anthropic
• Cline - Assistente de IA para VS Code

🙏 Agradecimentos

Construído com:

• Ollama SDK - Biblioteca JavaScript oficial do Ollama
• MCP SDK - SDK do Model Context Protocol
• Zod - Validação de schema TypeScript-first

---