使用说明

🦙 Ollama MCP服务器

通过本地LLM访问为您的AI助手充电

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

特性 • 安装 • 可用工具 • 配置 • 重试行为 • 发展

✨ 特性

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

💡 使用Claude Code和桌面升级您的Ollama体验

完整套餐：工具+知识

此MCP服务器为Claude提供了工具与Ollama互动，但通过安装 奥拉玛技能 从技能市场:

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

Ollama技能教克劳德：

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

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

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

结果：克劳德不仅有车，而且知道怎么开车！ 🏎️

📦 安装

Claude Desktop快速入门

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

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

全球安装

npm install -g ollama-mcp

对于Cline（VS代码）

添加到您的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`	从模型文件创建自定义模型

模型操作

工具	说明
`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云配置

要使用具有网络搜索和获取功能的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密钥）
📄 Web获取 ollama_web_fetch （需要API密钥）
🚀 更快地推断云基础架构

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

混合模式（本地+云）

您可以通过指向本地Ollama实例同时提供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"
      }
    }
  }
}

此配置：

✅ 从Ollama实例运行本地模型
✅ 启用仅限云的web搜索和获取工具
✅ 两全其美：隐私+网络连接

🔄 重试行为

MCP服务器包括智能重试逻辑，用于在与Ollama API通信时处理瞬态故障：

自动重试策略

Web工具(ollama_web_search 和 ollama_web_fetch):

在出现速率限制错误时自动重试（HTTP 429）
……的最大值 3次重试尝试 （共4个请求，包括初始请求）
请求超时： 每个请求30秒（防止挂起连接）
尊敬 Retry-After API提供的标头
当出现抖动时，会回落到指数回退 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))

重试延迟示例：

第一次重试：0-1秒
第二次重试：0-2秒
第三次重试：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临时问题的稳健处理，同时尊重服务器提供的重试指导并防止过高的请求率。对于所使用的幂等POST操作，可以安全地重试瞬态5xx错误（500、502、503、504） ollama_web_search 和 ollama_web_fetch。单个请求在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%

添加新工具

创建 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';
  }
};

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

🤝 贡献

欢迎投稿！请遵循以下指南：

分叉存储库
创建特征分支(git checkout -b feature/amazing-feature)
编写测试 -我们保持96%以上的覆盖率
提交信息清晰(git commit -m 'Add amazing feature')
推到您的分行(git push origin feature/amazing-feature)
打开拉取请求

代码质量标准

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

📄 许可证

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

看许可证了解详情。

🔗 相关项目

技能市场 -Claude代码技能，包括Ollama技能
奥拉玛 -在本地启动并运行大型语言模型
模型上下文协议 -AI助手集成的开放标准
克劳德桌面 -Anthropic的桌面应用程序
克莱恩 -VS代码AI助手

🙏 致谢

内置：

Ollama SDK -Ollama官方JavaScript库
MCP-SDK -模型上下文协议SDK
黄道 -TypeScript第一模式验证

⬆ 返回页首

由以下材料制成❤️ 靠近提姆·格林