Ollama MCP Server

Integre instâncias locais de LLM do Ollama com aplicativos compatíveis com MCP.

GitHub
6
Experimente este MCPPatrocinado

Documentação

ollama-MCP-server

Servidor Model Context Protocol (MCP) para comunicação com Ollama

Visão geral

Este servidor MCP permite integração perfeita entre instâncias locais de LLM Ollama e aplicativos compatíveis com MCP, fornecendo decomposição avançada de tarefas, avaliação e gerenciamento de fluxo de trabalho.

Principais recursos:

  • Decomposição de tarefas complexas em subtarefas
  • Avaliação e validação de resultados
  • Gerenciamento e execução de modelos Ollama
  • Comunicação padronizada via protocolo MCP
  • Tratamento avançado de erros com mensagens de erro detalhadas
  • Otimização de desempenho (pool de conexões, cache LRU)

Componentes

Recursos

O servidor implementa os seguintes recursos:

  • task:// - esquema de URI para acessar tarefas individuais
  • result:// - esquema de URI para acessar resultados de avaliação
  • model:// - esquema de URI para acessar modelos Ollama disponíveis

Cada recurso possui metadados e tipos MIME apropriados para interação ideal com LLM.

Relação entre prompts e ferramentas

No servidor MCP, prompts e ferramentas estão intimamente relacionados, mas possuem papéis diferentes.

  • Prompts: funcionam como esquemas (Schema) que fornecem métodos específicos de pensamento ou estrutura ao LLM
  • Ferramentas: funcionam como manipuladores (Handler) que executam ações de fato

Cada ferramenta requer um esquema (prompt) correspondente, permitindo que a capacidade de raciocínio do LLM e as funcionalidades reais do sistema trabalhem juntas de forma eficaz.

Prompts

O servidor fornece vários prompts especiais:

  • decompose-task - decompõe tarefas complexas em subtarefas gerenciáveis

    • Recebe a descrição da tarefa e parâmetros opcionais de nível de granularidade
    • Retorna uma decomposição estruturada incluindo dependências e complexidade estimada

  • evaluate-result - analisa resultados de tarefas em relação a critérios especificados

    • Recebe o conteúdo do resultado e parâmetros de avaliação
    • Retorna uma avaliação detalhada incluindo pontuação e sugestões de melhoria

Ferramentas

O servidor implementa várias ferramentas poderosas:

  • add-task

    • Parâmetros obrigatórios: name (string), description (string)
    • Parâmetros opcionais: priority (número), deadline (string), tags (array)
    • Cria uma nova tarefa no sistema e retorna seu identificador
    • Esquema correspondente: esquema de validação de dados para criação de tarefas

  • decompose-task

    • Parâmetros obrigatórios: task_id (string), granularity (string: "high"|"medium"|"low")
    • Parâmetros opcionais: max_subtasks (número)
    • Usa Ollama para decompor tarefas complexas em subtarefas gerenciáveis
    • Esquema correspondente: prompt decompose-task acima

  • evaluate-result

    • Parâmetros obrigatórios: result_id (string), criteria (objeto)
    • Parâmetros opcionais: detailed (booleano)
    • Avalia resultados em relação a critérios especificados e fornece feedback
    • Esquema correspondente: prompt evaluate-result acima

  • run-model

    • Parâmetros obrigatórios: model (string), prompt (string)
    • Parâmetros opcionais: temperature (número), max_tokens (número)
    • Executa modelos Ollama com parâmetros especificados
    • Esquema correspondente: esquema de validação de parâmetros de execução do modelo Ollama

Novos recursos e melhorias

Tratamento de erros aprimorado

O servidor fornece mensagens de erro mais detalhadas e estruturadas, permitindo que aplicativos clientes tratem erros de forma mais eficaz. Exemplo de resposta de erro:

{
  "error": {
    "message": "Task not found: task-123",
    "status_code": 404,
    "details": {
      "provided_id": "task-123"
    }
  }
}

Otimização de desempenho

  • Pool de conexões: o uso de um pool compartilhado de conexões HTTP melhora o desempenho de requisições e reduz o uso de recursos.
  • Cache LRU: o cache de respostas para requisições idênticas ou semelhantes reduz o tempo de resposta e alivia a carga do servidor Ollama.

Essas configurações podem ser ajustadas em config.py:

# パフォーマンス関連設定
cache_size: int = 100                 # キャッシュに保存する最大エントリ数
max_connections: int = 10             # 同時接続の最大数
max_connections_per_host: int = 10    # ホストごとの最大接続数
request_timeout: int = 60             # リクエストタイムアウト（秒）

Funcionalidade de especificação de modelo

Visão geral

O Ollama-MCP-Server oferece funcionalidade flexível para especificar modelos Ollama de várias maneiras.

Prioridade de especificação de modelo

Os modelos são especificados na seguinte ordem de prioridade:

  1. Parâmetro na chamada da ferramenta (parâmetro model)
  2. Seção env do arquivo de configuração MCP
  3. Variável de ambiente (OLLAMA_DEFAULT_MODEL)
  4. Valor padrão (llama3)

Especificação de modelo usando arquivo de configuração MCP

Ao usar com clientes como Claude Desktop, você pode especificar o modelo usando o arquivo de configuração MCP:

{
  "mcpServers": {
    "ollama-MCP-server": {
      "command": "python",
      "args": [
        "-m",
        "ollama_mcp_server"
      ],
      "env": [
        {"model": "llama3:latest"}
      ]
    }
  }
}

Verificação de modelos disponíveis

Na inicialização do servidor, é verificado se o modelo configurado existe. Se o modelo não for encontrado, um log de aviso é emitido. Além disso, a ferramenta run-model retorna a lista de modelos disponíveis, permitindo que o usuário selecione um modelo válido.

Melhorias no tratamento de erros

Se o modelo especificado não existir ou ocorrer um erro de comunicação, mensagens de erro detalhadas são fornecidas. As mensagens de erro incluem a lista de modelos disponíveis, permitindo que o usuário resolva o problema rapidamente.

Testes

O projeto inclui uma suíte de testes abrangente:

  • Testes unitários: testam a funcionalidade de componentes individuais
  • Testes de integração: testam fluxos de trabalho de ponta a ponta

Para executar os testes:

# すべてのテストを実行
python -m unittest discover

# 特定のテストを実行
python -m unittest tests.test_integration

Configuração

Variáveis de ambiente

OLLAMA_HOST=http://localhost:11434
DEFAULT_MODEL=llama3
LOG_LEVEL=info

Configuração do Ollama

Certifique-se de que o Ollama esteja instalado e executando com os modelos apropriados:

# Ollamaをインストール（まだインストールされていない場合）
curl -fsSL https://ollama.com/install.sh | sh

# 推奨モデルをダウンロード
ollama pull llama3
ollama pull mistral
ollama pull qwen2

Início rápido

Instalação

pip install ollama-mcp-server

Configuração do Claude Desktop

MacOS

Caminho: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

Caminho: %APPDATA%/Claude/claude_desktop_config.json

Configuração para servidores de desenvolvimento/não publicados 
"mcpServers": {
  "ollama-MCP-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ollama-MCP-server",
      "run",
      "ollama-MCP-server"
    ],
    "ENV":["model":"deepseek:r14B"]
  }
}
Configuração para servidores públicos 
"mcpServers": {
  "ollama-MCP-server": {
    "command": "uvx",
    "args": [
      "ollama-MCP-server"
    ]
  }
}

Exemplos de uso

Decomposição de tarefas

Para decompor uma tarefa complexa em subtarefas gerenciáveis:

result = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "decompose-task",
    "arguments": {
        "task_id": "task://123",
        "granularity": "medium",
        "max_subtasks": 5
    }
})

Avaliação de resultados

Para avaliar um resultado em relação a critérios específicos:

evaluation = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "evaluate-result",
    "arguments": {
        "result_id": "result://456",
        "criteria": {
            "accuracy": 0.4,
            "completeness": 0.3,
            "clarity": 0.3
        },
        "detailed": true
    }
})

Execução de modelos Ollama

Para executar consultas diretamente em modelos Ollama:

response = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "run-model",
    "arguments": {
        "model": "llama3",
        "prompt": "量子コンピューティングを簡単な言葉で説明してください",
        "temperature": 0.7
    }
})

Desenvolvimento

Configuração do projeto

  1. Clone o repositório:
git clone https://github.com/yourusername/ollama-MCP-server.git
cd ollama-MCP-server
  1. Crie e ative o ambiente virtual:
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
  1. Instale as dependências de desenvolvimento:
uv sync --dev --all-extras

Desenvolvimento local

O projeto inclui scripts de desenvolvimento convenientes:

Executando o servidor

./run_server.sh

Opções:

  • --debug: executar em modo de depuração (nível de log: DEBUG)
  • --log=LEVEL: especificar o nível de log (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Executando testes

./run_tests.sh

Opções:

  • --unit: executar apenas testes unitários
  • --integration: executar apenas testes de integração
  • --all: executar todos os testes (padrão)
  • --verbose: saída detalhada de testes

Build e publicação

Para preparar o pacote para distribuição:

  1. Sincronize as dependências e atualize o arquivo de bloqueio:
uv sync
  1. Compile os artefatos de distribuição do pacote:
uv build

Isso criará artefatos de distribuição de fonte e wheel no diretório dist/.

  1. Publique no PyPI:
uv publish

Nota: você precisa definir as credenciais do PyPI via variáveis de ambiente ou flags de comando:

  • Token: --token ou UV_PUBLISH_TOKEN
  • Ou nome de usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como o servidor MCP é executado via stdio, a depuração pode ser difícil. Para a melhor experiência de depuração, é altamente recomendado usar o MCP Inspector.

Para iniciar o MCP Inspector usando npm, execute o seguinte comando:

npx @modelcontextprotocol/inspector uv --directory /path/to/ollama-MCP-server run ollama-mcp-server

Na inicialização, o Inspector exibirá uma URL que pode ser acessada no navegador para iniciar a depuração.

Arquitet

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar pull requests.

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das alterações (git commit -m 'Add some amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um pull request

Licença

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

Agradecimentos

  • Equipe do Model Context Protocol pelo excelente design do protocolo
  • Projeto Ollama por tornar a execução local de LLMs acessível
  • Todos os contribuidores deste projeto