使用说明
Ollama MCP服务器
一个自给自足的 模型上下文协议（MCP）服务器 在Claude AI的协助下开发的Ollama本地管理系统。功能包括列出本地模型、聊天、启动/停止服务器，以及一个“本地模型顾问”，为给定任务建议最佳的本地模型。该服务器旨在成为一个健壮、无依赖性和跨平台的工具，用于管理本地Ollama实例。
⚠️ 当前测试状态
目前正在测试：配备NVIDIA RTX 4090的Windows 11
状态：Windows测试版，其他平台需要测试
跨平台代码：已为Linux和macOS做好准备，但需要社区测试
GPU支持：NVIDIA经过全面测试，AMD/Intel/Apple Silicon已实施，但需要验证
我们欢迎不同平台和硬件配置的测试人员！请通过GitHub Issues报告您的体验。
🎯 主要特点
🔧 自给自足的架构
- 零外部依赖：不需要外部MCP服务器
- MIT许可证就绪：所有内部开发并获得适当许可的代码
- 企业级：专业的错误处理和可操作的故障排除
🌐 通用兼容性
- 交叉平台的：Windows、Linux、macOS，具有自动平台检测功能
- 多GPU支持：NVIDIA、AMD、Intel检测，具有供应商特定的优化
- 智能安装发现：跨平台自动检测Olama
⚡ 完成当地Ollama管理
- 模型操作：列出、建议和删除本地模型。
- 服务器控件：通过智能流程管理启动和监控Ollama服务器。
- 直接聊天：与任何本地安装的模型进行通信。
- 系统分析：评估硬件兼容性并监控资源。
🚀 快速开始
安装
git clone https://github.com/paolodalprato/ollama-mcp-server.git
cd ollama-mcp-server
pip install -e .
配置
添加到您的MCP客户端配置中（例如，Claude Desktop config.json):
{
"mcpServers": {
"ollama-mcp": {
"command": "python",
"args": [
"X:\\PATH_TO\\ollama-mcp-server\\src\\ollama_mcp\\server.py"
],
"env": {}
}
}
}
备注：调整路径以匹配您的安装目录。在Linux/macOS上，使用正斜杠： /path/to/ollama-mcp-server/src/ollama_mcp/server.py
需求
- Python 3.10+ （MCP SDK依赖项要求）
- Ollama已安装 可在PATH中访问
- MCP兼容客户端 （克劳德桌面等）
Ollama配置兼容性
此MCP服务器会自动遵守您的Ollama配置。如果您已经自定义了Ollama设置（例如，通过以下方式更改了模型文件夹 OLLAMA_MODELS 环境变量），MCP服务器将无缝工作，无需任何额外配置。
🛠️ 可用工具
模型管理
list_local_models-列出所有本地安装的型号及其详细信息。local_llm_chat-直接与任何本地安装的型号聊天。remove_model-从本地存储中安全删除模型。suggest_models-推荐最好的 本地安装 特定任务的模型（例如“建议编码模型”）。
服务器和系统操作
start_ollama_server-如果Ollama服务器尚未运行，则启动它。ollama_health_check-对Ollama服务器执行全面的健康检查。system_resource_check-分析系统硬件和资源可用性。
诊断
test_model_responsiveness-通过发送测试提示来检查特定本地模型的响应性，帮助诊断性能问题。select_chat_model-在开始聊天之前，显示可供选择的本地型号列表。
💬 如何与Olama MCP互动
Olama MCP工厂 通过您的MCP客户端 （就像克劳德桌面）-你不直接与它交互。相反，您可以使用以下方式与MCP客户端通信 自然语言，客户端将您的请求转换为工具调用。
基本交互模式
您用自然语言与MCP客户端对话，它会自动使用适当的ollama-MCP工具：
You: "List my installed Ollama models"
→ Client calls: list_local_models
→ You get: Formatted list of your models
You: "Chat with llama3.2: explain machine learning"
→ Client calls: local_llm_chat with model="llama3.2" and message="explain machine learning"
→ You get: AI response from your local model
You: "Check if Ollama is running"
→ Client calls: ollama_health_check
→ You get: Server status and troubleshooting if needed
交互示例
模型管理
- “我安装了哪些型号？” →
list_local_models - “我需要一个创意写作的模型，我的哪个模型最好？” →
suggest_models - “删除旧的mistral模型以节省空间” →
remove_model
系统操作
- “启动Ollama服务器” →
start_ollama_server - “我的系统能够运行大型人工智能模型吗？” →
system_resource_check
AI聊天
- “与llama3.2聊天：编写Python函数对列表进行排序” →
local_llm_chat - “使用deepseek编码器调试此代码：[代码片段]” →
local_llm_chat - “让phi3.5简单解释量子计算” →
local_llm_chat
要点
- 无直接命令：你从不打电话
ollama_health_check()直接 - 自然语言：与您的MCP客户正常交谈
- 自动刀具选择：客户根据您的要求选择合适的工具
- 对话式：您可以提出后续问题，客户可以维护上下文
🎯 真实世界用例
日常开发工作流程
“我需要做一个编码项目。我的哪种本地模型最适合编码？让我们检查它的性能，然后问它一个问题。”
这可能会触发：
suggest_models-推荐最佳的本地“编码”模型。test_model_responsiveness-检查推荐的型号是否响应。local_llm_chat-开始与模特聊天。
模型管理会议
“给我看看我有什么模型，并推荐一个用于写故事。然后让我们清理掉我不需要的旧模型。”
触发器：
list_local_models-当前库存suggest_models-推荐一个当地的“写故事”模式。remove_model-清理不需要的模型。
故障排除会话
“Ollama不工作。检查出了什么问题，试着修复它，然后通过简单的聊天进行测试。”
触发器：
ollama_health_check-诊断问题start_ollama_server-尝试启动服务器local_llm_chat-验证是否使用测试消息
🏗️ 建筑
设计原则
- 独立：零外部MCP服务器依赖关系
- 故障保险：全面的错误处理和可操作的指导
- 跨平台优先：通用Windows/Linux/macOS兼容性
- 企业就绪：专业级实施和文件编制
技术亮点
- 内部流程管理：具有超时控制的高级子流程处理
- 多GPU检测：平台特定的GPU识别，而不会混淆指标
- 智能选型：未指定时回退到第一个可用型号
- 渐进式健康监测：智能服务器启动检测，并提供详细反馈
📋 系统兼容性
操作系统
- 视窗：完全支持程序文件和AppData中的自动检测✅ 已测试
- Linux：XDG配置支持与包管理器集成⚠️ 需要测试
- macOS：支持Apple Silicon GPU的自制检测⚠️ 需要测试
GPU支持
- 英伟达：通过nvidia smi进行全面检测，并提供内存和利用率信息✅ 经过测试的RTX 4090
- 超威半导体：通过供应商特定工具提供ROCm支持⚠️ 需要测试
- 英特尔：通过系统工具进行基本检测⚠️ 需要测试
- 苹果芯片：具有统一内存处理的M1/M2/M3检测⚠️ 需要测试
硬件要求
- 最小：4GB RAM，2GB可用磁盘空间
- 推荐：8GB+RAM，10GB+可用磁盘空间
- 图形处理器：可选，但建议用于模型加速
🔧 发展
项目结构
ollama-mcp-server/
├── src/
│ ├── __init__.py # Defines the package version
│ └── ollama_mcp/
│ ├── __init__.py # Makes 'ollama_mcp' a package
│ ├── server.py # Main MCP server implementation
│ ├── client.py # Ollama API client
│ ├── config.py # Configuration management
│ ├── model_manager.py # Local model operations
│ ├── hardware_checker.py # System hardware analysis
│ └── ... (and other modules)
├── tests/
│ ├── test_client.py # Unit tests for the client
│ └── test_tools.py # Integration tests for tools
├── .gitignore # Specifies intentionally untracked files
└── pyproject.toml # Project configuration and dependencies
关键技术成果
独立实施
- 挑战：消除外部
desktop-commander依赖 - 解决方案：具有高级子流程处理功能的内部流程管理
- 结果：零外部MCP依赖，兼容MIT许可证
智能GPU检测
- 挑战：复杂的VRAM报告导致用户困惑
- 解决方案：仅简化为GPU名称显示
- 结果：干净、可靠的硬件标识
企业错误处理
- 实施：具有特定错误类型的6级异常框架
- 覆盖：平台特定错误、流程故障、网络问题
- 用户体验：针对每种错误情况的可操作故障排除步骤
🤝 贡献
我们欢迎捐款！特别需要帮助的领域：
- 平台测试：不同的操作系统和硬件配置⭐ 高优先级
- GPU供应商支持：额外的供应商特定检测
- 性能优化：启动时间和资源使用的改进
- 文档：使用示例和集成指南
- 测试：边缘情况和错误条件验证
即时测试需求
- Linux：Ubuntu、Fedora、Arch，具有各种GPU配置
- macOS：安装了不同Ollama的英特尔和苹果Silicon Mac
- GPU供应商：AMD ROCm、英特尔Arc、苹果统一内存
- 边缘案例：不同的Python版本，不同的Ollama安装方法
开发设置
git clone https://github.com/paolodalprato/ollama-mcp-server.git
cd ollama-mcp-server
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Code formatting
black src/
isort src/
# Type checking
mypy src/
🐛 故障排除
常见问题
找不到Ollama
# Verify Ollama installation
ollama --version
# Check PATH configuration
which ollama # Linux/macOS
where ollama # Windows
服务器启动失败
# Check port availability
netstat -an | grep 11434
# Manual server start for debugging
ollama serve
权限问题
- 视窗：如果需要，以管理员身份运行
- Linux/macOS：检查服务管理的用户权限
平台特定问题
如果您在Linux或macOS上遇到问题，请通过GitHub issues报告：
- 操作系统和版本
- Python版本
- Ollama版本和安装方法
- GPU硬件（如适用）
- 完整的错误输出
📊 演出
典型响应时间 （Windows RTX 4090）
- 健康检查：<500ms
- 模型列表：<1秒
- 服务器启动：1-15秒（取决于硬件）
- 模特聊天：2-30秒（取决于型号和提示）
资源使用情况
- 记忆：MCP服务器进程小于50MB
- 中央处理器：闲置时最小，随操作而扩展
- 存储：仅配置文件和日志
🔐 安全
- 数据流：用户→ MCP客户端（克劳德）→ ollama mcp服务器→ 当地Ollama→ 通过链条返回
👨💻 关于本项目
这是我的第一台MCP服务器，它是通过改编我为自己的Ollama管理需求开发的个人工具而创建的。
我面临的问题
我开始使用Claude与Ollama交互，因为它允许我使用自然语言而不是命令行界面。Claude还提供了Ollama独有的功能，特别是基于我的系统功能和特定需求的智能模型建议。
我的解决方案
我构建了这个MCP服务器来简化我自己的工作流程，然后将其改进为其他人可能会觉得有用的稳定工具。该设计反映了真实的使用模式：
- 自足：没有可以破坏的外部依赖关系
- 智能错误处理：事情出错时有明确的指导
- 跨平台：在不同环境中工作一致
- 实用工具：我在日常工作中实际使用的功能
设计理念
我最初开发这个是为了更有效地管理Olama模型。当MCP协议可用时，我将我的个人工具转换为MCP服务器，与可能发现它有用的其他人共享。
开发方法：这个项目是与Claude一起使用“vibe编码”开发的，这是一个迭代的、对话式的开发过程，人工智能的帮助有助于完善技术实施和用户体验。这是人工智能辅助开发为人工智能管理创建工具的一个实例。Jules还参与了最后的重构阶段。
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- Ollama团队：优秀的本地AI平台
- MCP项目：用于模型上下文协议规范
- 克劳德桌面/代码由Anthropic：作为MCP客户端实现、测试和重构的工具
- 谷歌朱尔斯：作为重构的工具
📞 支持
更新日志
- v0.9.0（2025年8月17日）： 关键错误修复版本-修复了阻止模型列表与Claude Desktop一起工作的日期时间序列化问题。现在，所有9个工具都已验证工作正常。
- 2025年8月： 项目重构和增强。彻底改革了模块化架构，实现了一个完全异步的客户端，添加了一个测试套件，并根据“本地优先”的理念改进了工具逻辑。
- 2025年7月： 初始版本由Paolo Dalprato在Claude AI的协助下创建。
有关详细更改，请参阅 更改日志.md.
状态：Windows测试版，其他平台需要测试
测试：Windows 11+RTX 4090经过验证，Linux/macOS需要社区验证
许可证：MIT
依赖项：无需外部MCP服务器