Ollama MCP Server with

Ollama MCP 服务

一款功能全面的 Ollama 集成 Model Context Protocol（MCP）服务，提供脚本管理、多 Agent 工作流和进程泄漏防护等高级功能。

🌟 功能

• 🔄 异步任务管理：在后台执行长时间运行的任务
• 📝 脚本模板：创建支持变量替换的可复用提示词模板
• 🤖 Fast-Agent 集成：多 Agent 工作流（链式、并行、路由、评估）
• 🛡️ 进程泄漏防护：妥善清理和管理资源
• 📊 全面监控：任务跟踪、状态监控和输出管理
• 🎯 内置提示词：为常见任务提供交互式指导模板
• ⚡ 多模型支持：使用本地安装的任意 Ollama 模型

🚀 快速开始

前置条件

• 安装了 uv 包管理器的 Python 3.8+
• 已安装并运行 Ollama
• 用于 MCP 集成的 Claude Desktop

安装

1. 设置环境： 请注意：此 README 由一个不太用心的 AI 修改过。

cd /path/to/ollama-mcp-server
uv venv --python 3.12 --seed
source .venv/bin/activate
uv add mcp[cli] python-dotenv

2. 配置 Claude Desktop： 将 example_of_bad_ai_gen_mcp_config_do_not_use.json 中的配置复制到 Claude Desktop 配置文件中。（千万别这么做。请使用 example_claude_desktop_config.json）：

• Linux：~/.config/Claude/claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

3. 更新配置中的路径，使其与系统相符

4. 重启 Claude Desktop

🛠️ 可用工具

核心操作

• list_ollama_models - 显示所有可用的 Ollama 模型
• run_ollama_prompt - 使用任意模型执行提示词（同步/异步）
• get_job_status - 检查任务完成状态
• list_jobs - 查看所有正在运行和已完成的任务
• cancel_job - 停止正在运行的任务

脚本管理

• save_script - 创建可复用的提示词模板
• list_scripts - 查看已保存的模板
• get_script - 读取模板内容
• run_script - 使用变量执行模板

Fast-Agent 工作流

• create_fastagent_script - 单 Agent 脚本
• create_fastagent_workflow - 多 Agent 工作流
• run_fastagent_script - 执行 Agent 工作流
• list_fastagent_scripts - 查看可用工作流

系统集成

• run_bash_command - 安全地执行系统命令
• run_workflow - 执行多步骤工作流

📖 内置提示词

用于指导常见任务的交互式提示词：

• ollama_guide - 交互式用户指南
• ollama_run_prompt - 简单的提示词执行
• model_comparison - 比较多个模型
• fast_agent_workflow - 多 Agent 工作流
• script_executor - 模板执行
• batch_processing - 处理多个提示词
• iterative_refinement - 内容改进工作流

📁 目录结构

ollama-mcp-server/
├── src/ollama_mcp_server/
│   └── server.py                 # Main server code
├── outputs/                      # Generated output files
├── scripts/                      # Saved script templates
├── workflows/                    # Workflow definitions
├── fast-agent-scripts/          # Fast-agent Python scripts
├── prompts/                      # Usage guides
│   ├── tool_usage_guide.md
│   ├── prompt_templates_guide.md
│   └── setup_guide.md
├── example_mcp_config.json      # Claude Desktop config
└── README.md

🔧 开发

运行开发服务

cd ollama-mcp-server
uv run python -m ollama_mcp_server.server

使用 MCP Inspector 调试

mcp dev src/ollama_mcp_server/server.py

🛡️ 进程管理

此服务全面防止进程泄漏：

• 信号处理：正确处理 SIGTERM/SIGINT
• 后台任务跟踪：监控所有异步任务
• 资源清理：自动终止进程
• 内存管理：防止僵尸进程累积

通过以下命令监控运行状况：

ps aux | grep mcp | wc -l  # Should show <10 processes

📊 使用示例

简单提示词执行

1. Use "ollama_run_prompt" prompt in Claude
2. Specify model and prompt text
3. Get immediate results

多 Agent 工作流

1. Use "fast_agent_workflow" prompt
2. Choose workflow type (chain/parallel/router/evaluator)
3. Define agents and initial prompt
4. Monitor execution

脚本模板

1. Create template with save_script
2. Use variables: {variable_name}
3. Execute with run_script
4. Pass JSON variables object

🚨 故障排除

找不到模型：使用 list_ollama_models 获取准确名称
连接问题：使用 ollama serve 启动 Ollama
进程数过多：服务现在会自动防止进程泄漏
任务卡住：使用 cancel_job 停止有问题的任务

🤝 贡献

1. 遵循 MCP Python SDK 开发指南
2. 使用恰当的类型提示和文档字符串
3. 全面测试所有新功能
4. 确保所有代码路径都能清理进程

📄 许可证

本项目遵循与 MCP Python SDK 相同的许可条款。

🙏 致谢

本项目基于 Model Context Protocol 和 Ollama 构建，并采用了 MCP 最佳实践中的进程管理模式。

---

准备好开始了吗？ 请查看 prompts/setup_guide.md，了解详细的安装说明！