奥拉玛-MCP

Name: 奥拉玛-MCP
Author: rawveg

作者：rawveg117 星标更新：2025-11-11

安装使用来源：spider==github.com

项目介绍

🦙 Ollama MCP 服务器

通过本地LLM访问增强您的AI助手

一个MCP（模型上下文协议）服务器，公开完整的Ollama SDK作为MCP工具，实现本地LLM模型与兼容MCP的应用程序（如Claude Desktop和Cline）之间的无缝集成。

功能 • 安装 • 可用工具 • 配置 • 重试行为 • 开发

</div>

✨ 功能

☁️ Ollama云支持 - 完整集成Ollama的云平台
🔧 14种全面工具 - 全面访问Ollama的SDK功能
🔄 热插拔架构 - 自动发现工具，无需配置
🎯 类型安全 - 使用TypeScript和Zod验证构建
📊 高测试覆盖率 - 超过96%的测试覆盖率
🚀 零依赖 - 最小占用，最大性能
🔌 即插即用集成 - 适用于Claude Desktop、Cline和其他MCP客户端
🌐 网络搜索与抓取 - 实时网络搜索和内容提取，通过Ollama云
🔀 混合模式 - 在一台服务器上无缝使用本地和云端模型

💡 提升您的Ollama体验，结合Claude代码和桌面版

完整包：工具 + 知识

此MCP服务器赋予Claude与Ollama交互的工具——但您还可以通过从Skillsforge Marketplace安装Ollama技能获得更多价值：

🚗 此MCP = 汽车 - 所有工具和能力
🎓 Ollama技能 = 驾驶课程 - 如何有效使用它们的专业知识

Ollama技能教会Claude：

模型选择和配置的最佳实践
不同Ollama模型的最佳提示策略
何时使用聊天、生成、嵌入和其他工具
性能优化和故障排除
高级功能，如工具调用和支持

安装两者以获得完整体验：

✅ 此MCP服务器（工具）
✅ Ollama技能（专业知识）

结果：Claude不仅拥有汽车——它还知道如何驾驶！ 🏎️

📦 安装

快速开始使用Claude Desktop

添加到您的Claude Desktop配置文件（macOS上的~/Library/Application Support/Claude/claude_desktop_config.json）：

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

全局安装

npm install -g ollama-mcp

对于Cline（VS Code）

添加到您的Cline MCP设置（cline_mcp_settings.json）：

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

🛠️ 可用工具

模型管理

工具	描述
`ollama_list`	列出所有可用的本地模型
`ollama_show`	获取特定模型的详细信息
`ollama_pull`	从Ollama库下载模型
`ollama_push`	将模型推送到Ollama库
`ollama_copy`	创建现有模型的副本
`ollama_delete`	从本地存储中删除模型
`ollama_create`	从Modelfile创建自定义模型

模型操作

工具	描述
`ollama_ps`	列出当前运行的模型
`ollama_generate`	生成文本补全
`ollama_chat`	与模型进行交互式聊天（支持工具/函数）
`ollama_embed`	为文本生成嵌入

网络工具（Ollama云）

工具	描述
`ollama_web_search`	使用可定制的结果限制搜索网络（需要`OLLAMA_API_KEY`）
`ollama_web_fetch`	抓取并解析网页内容（需要`OLLAMA_API_KEY`）

注意：网络工具需要Ollama云API密钥。它们连接到https://ollama.com/api进行网络搜索和抓取操作。

⚙️ 配置

环境变量

变量	默认值	描述
`OLLAMA_HOST`	`http://127.0.0.1:11434`	Ollama服务器端点（使用`https://ollama.com`用于云）
`OLLAMA_API_KEY`	-	Ollama云的API密钥（用于网络工具和云模型）

自定义Ollama主机

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

Ollama云配置

要使用Ollama的云平台以及网络搜索和抓取功能：

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

云功能：

☁️ 访问托管在云中的模型
🔍 使用ollama_web_search进行网络搜索（需要API密钥）
📄 使用ollama_web_fetch抓取网页内容（需要API密钥）
🚀 在云基础设施上更快地推理

获取您的API密钥：访问ollama.com注册并获取您的API密钥。

混合模式（本地 + 云）

您可以同时使用本地和云模型，指向您的本地Ollama实例并提供API密钥：

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

此配置：

✅ 运行来自您的Ollama实例的本地模型
✅ 启用仅限云的网络搜索和抓取工具
✅ 结合了两者的优点：隐私 + 网络连接

🔄 重试行为

MCP服务器包括智能重试逻辑，用于处理与Ollama API通信时出现的瞬态失败：

自动重试策略

网络工具（ollama_web_search 和 ollama_web_fetch）：

自动重试因速率限制错误（HTTP 429）而失败的情况
最多3次重试尝试（总共4次请求，包括初始请求）
请求超时：每个请求30秒（防止挂起连接）
当API提供时尊重Retry-After头
当没有提供Retry-After时回退到带有抖动的指数退避

Retry-After头支持

服务器智能处理标准HTTP Retry-After头的两种格式：

1. 延迟-秒数格式：

Retry-After: 60

等待恰好60秒后重试。

2. HTTP-日期格式：

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

计算直到指定时间戳的延迟。

指数退避

当未提供或提供的Retry-After无效时：

初始延迟：1秒（默认）
最大延迟：10秒（默认，可配置）
策略：带有完全抖动的指数退避
公式：random(0, min(initialDelay × 2^attempt, maxDelay))

示例重试延迟：

第1次重试：0-1秒
第2次重试：0-2秒
第3次重试：0-4秒（上限为0-10秒）

错误处理

重试错误（瞬态失败）：

HTTP 429（太多请求） - 速率限制
HTTP 500（内部服务器错误） - 瞬态服务器问题
HTTP 502（坏网关） - 网关/代理收到无效响应
HTTP 503（服务不可用） - 服务器暂时无法处理请求
HTTP 504（网关超时） - 网关/代理未及时收到响应

不重试错误（永久失败）：

请求超时（超过30秒限制）
网络超时（无状态码）
中断/取消错误
HTTP 4xx错误（除429外） - 需要更改的客户端错误
其他HTTP 5xx错误（501, 505, 506, 508等） - 配置/实现问题

重试机制确保了临时API问题的健壮处理，同时尊重服务器提供的重试指导，并防止过度请求率。瞬态5xx错误（500, 502, 503, 504）对于ollama_web_search和ollama_web_fetch使用的幂等POST操作是安全的。单个请求超时30秒以防止无限期挂起连接。

🎯 使用示例

与模型聊天

// MCP客户端可以调用：
{
  "tool": "ollama_chat",
  "arguments": {
    "model": "llama3.2:latest",
    "messages": [
      { "role": "user", "content": "解释量子计算" }
    ]
  }
}

生成嵌入

{
  "tool": "ollama_embed",
  "arguments": {
    "model": "nomic-embed-text",
    "input": ["你好世界", "嵌入很棒"]
  }
}

网络搜索

{
  "tool": "ollama_web_search",
  "arguments": {
    "query": "最新的人工智能发展",
    "max_results": 5
  }
}

🏗️ 架构

此服务器使用热插拔自动加载器模式：

src/
├── index.ts          # 入口点（27行）
├── server.ts         # MCP服务器创建
├── autoloader.ts     # 动态工具发现
└── tools/            # 工具实现
    ├── chat.ts       # 每个导出toolDefinition
    ├── generate.ts
    └── ...

关键优势：

通过在src/tools/中放置文件来添加新工具
无需更改服务器代码
每个工具独立可测试
所有工具100%函数覆盖

🧪 开发

先决条件

Node.js v16+
npm 或 pnpm
本地运行的Ollama

设置

# 克隆仓库
git clone https://github.com/rawveg/ollama-mcp.git
cd ollama-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

测试覆盖率

语句   : 96.37%
分支   : 84.82%
函数   : 100%
行     : 96.37%

添加新工具

创建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: '您的工具描述',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    },
    required: ['param']
  },
  handler: async (ollama, args, format) => {
    // 实现
    return '结果';
  }
};

在tests/tools/your-tool.test.ts中创建测试
完成！自动加载器会自动发现它。

🤝 贡献

欢迎贡献！请遵循以下指南：

分叉仓库
创建特性分支（git checkout -b feature/amazing-feature）
编写测试 - 我们维护96%以上的覆盖率
提交具有清晰消息的更改（git commit -m '添加精彩功能'）
推送到您的分支（git push origin feature/amazing-feature）
打开拉取请求

代码质量标准

所有新工具必须导出toolDefinition
维持≥80%的测试覆盖率
遵循现有的TypeScript模式
使用Zod模式进行输入验证

📄 许可证

本项目根据GNU Affero通用公共许可证v3.0（AGPL-3.0）许可。

查看LICENSE了解详情。

🔗 相关项目

Skillsforge Marketplace - 包括Ollama技能在内的Claude代码技能
Ollama - 本地启动大型语言模型
模型上下文协议 - AI助手集成的开放标准
Claude Desktop - Anthropic的桌面应用程序
Cline - VS Code AI助手

🙏 致谢

由以下构建：

Ollama SDK - 官方Ollama JavaScript库
MCP SDK - 模型上下文协议SDK
Zod - TypeScript优先的模式验证

⬆ 返回顶部

由 Tim Green 制作 ❤️

</div>