Ollama MCP Server

---

✨ 功能

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

💡 使用 Claude Code 和 Desktop，全面提升 Ollama 体验

完整组合：工具 + 知识

此 MCP 服务为 Claude 提供了与 Ollama 交互的工具；此外，从 Skillsforge Marketplace 安装 Ollama Skill，还能获得更多价值：

• 🚗 此 MCP = 汽车 - 提供所有工具和功能
• 🎓 Ollama Skill = 驾驶课程 - 传授如何有效使用它们的专业知识

Ollama Skill 会教 Claude：

• 模型选择和配置的最佳实践
• 针对不同 Ollama 模型的最佳提示词策略
• 何时使用 chat、generate、embeddings 和其他工具
• 性能优化与故障排除
• 工具调用和函数支持等高级功能

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

1. ✅ 此 MCP 服务（工具）
2. ✅ Ollama Skill（专业知识）

结果：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	为文本生成嵌入向量

Web 工具（Ollama Cloud）

工具	描述
ollama_web_search	使用可自定义的结果数量限制搜索网页（需要 OLLAMA_API_KEY）
ollama_web_fetch	获取并解析网页内容（需要 OLLAMA_API_KEY）

注意： Web 工具需要 Ollama Cloud API 密钥。它们会连接到 https://ollama.com/api 执行网页搜索和获取操作。

⚙️ 配置

环境变量

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

自定义 Ollama 主机

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

Ollama Cloud 配置

如需使用 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 密钥。

混合模式（本地 + 云端）

你可以在提供 API 密钥的同时，将地址指向本地 Ollama 实例，从而同时使用本地和云端模型：

{
  "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"
      }
    }
  }
}

此配置：

• ✅ 在你的 Ollama 实例中运行本地模型
• ✅ 启用仅限云端的网页搜索和获取工具
• ✅ 兼得两者优势：隐私保护 + 网页连接能力

🔄 重试行为

MCP 服务包含智能重试逻辑，用于处理与 Ollama API 通信时出现的暂时性故障：

自动重试策略

Web 工具（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 问题，同时遵循服务端提供的重试建议，并避免请求频率过高。对于 ollama_web_search 和 ollama_web_fetch 使用的幂等 POST 操作，暂时性 5xx 错误（500、502、503、504）可以安全重试。每个请求会在 30 秒后超时，以防连接无限期挂起。

🎯 使用示例

与模型聊天

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

生成嵌入

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

网页搜索

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

🏗️ 架构

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

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
    └── ...

主要优势：

• 将文件放入 src/tools/ 即可添加新工具
• 无需修改任何服务代码
• 每个工具都可独立测试
• 所有工具的函数覆盖率均为 100%

🧪 开发

前置条件

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

设置

# 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

测试覆盖率

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

添加新工具

1. 创建 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. 在 tests/tools/your-tool.test.ts 中创建测试
3. 完成！自动加载器会自动发现它。

🤝 贡献

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

1. Fork 此仓库
2. 创建 功能分支（git checkout -b feature/amazing-feature）
3. 编写测试 - 我们会将覆盖率保持在 96% 以上
4. 使用清晰的消息提交（git commit -m 'Add amazing feature'）
5. 将更改推送到你的分支（git push origin feature/amazing-feature）
6. 创建 Pull Request

代码质量标准

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

📄 许可证

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）授权。

详情请参阅 LICENSE。

🔗 相关项目

• Skillsforge Marketplace - Claude Code 技能，包括 Ollama Skill
• Ollama - 在本地启动并运行大模型
• Model Context Protocol - 用于 AI 助手集成的开放标准
• Claude Desktop - Anthropic 的桌面应用
• Cline - VS Code AI 助手

🙏 致谢

使用以下项目构建：

• Ollama SDK - Ollama 官方 JavaScript 库
• MCP SDK - Model Context Protocol SDK
• Zod - TypeScript 优先的架构验证库

---