Ollama_MCP_Guidance

🎯 快速开始：如果您正在通过 LLM（如 Claude）使用本项目，请首先让 LLM 调用 get_started_guide 工具。这个入门指南将帮助 LLM 全面了解项目，从而为您提供更好的服务。

基于 MCP (Model Context Protocol) 的 Ollama API 交互服务。该项目提供了一个标准化的接口，用于与 Ollama 服务进行交互，并为 LLM 提供智能化的 API 调用指导。

⚠️ 项目状态说明：
这是一个 Cursor MCP Server 项目，目前仅支持在 Cursor 中使用
项目处于开发阶段，尚未实现 Ollama 的所有 API 端点
项目文档和注释采用中英双语，未来将统一为英文（并提供中文文档备份）

功能特点

✨ 标准化的 JSON 响应格式
🔍 完整的错误处理和状态反馈
📊 详细的性能指标统计
🛠 简单的配置管理
📚 内置的 API 文档导航

Related MCP server: mcp-server-ollama-deep-researcher

使用环境

本项目设计为 Cursor IDE 的 MCP 服务
需要在 Cursor 中通过 MCP 协议调用
不提供独立的客户端实现

安装

确保已安装 Python 3.10 或更高版本
安装 Ollama
安装项目：

# 安装 uv（推荐） curl -LsSf https://astral.sh/uv/install.sh | sh # 创建并激活虚拟环境 uv venv source .venv/bin/activate # Linux/macOS # 或 .venv\Scripts\activate # Windows # 安装依赖 uv pip install .

配置

项目使用 config.json 进行配置，主要配置项包括：

{ "ollama": { "host": "http://localhost:11434", // Ollama 服务地址 "timeout": 30, // 请求超时时间（秒） "user_agent": "Ollama_MCP_Guidance/1.0" // 请求标识 }, "api_doc": { "max_length": 8000, // 文档内容最大长度 "file_path": "ollama-api.md" // API 文档路径 } }

使用

📌 重要提示：如果您正在与 AI 助手交互，请确保它已经调用了 get_started_guide 工具。这个入门指南包含了完整的使用说明和最佳实践，可以帮助 AI 更好地理解您的需求并提供准确的帮助。

1. 创建运行脚本

由于 Cursor MCP 需要从默认命令行环境中执行单条命令，建议创建一个自定义运行脚本。创建 ollama-mcp-cli 文件（以下以 macOS/Linux 为例）：（如果有不理解的地方，请提供信息，让AI来帮助你）

#!/bin/bash # 虚拟环境配置 # 如果使用 conda，取消下面的注释并修改路径 # CONDA_PATH="你的conda路径/etc/profile.d/conda.sh" # if [ -f "$CONDA_PATH" ]; then # source "$CONDA_PATH" # conda activate 你的环境名称 # fi # 项目路径配置 PROJECT_PATH="你的项目路径/Ollama_MCP_Guidance" if [ ! -d "$PROJECT_PATH" ]; then echo "Error: Project directory not found at $PROJECT_PATH" exit 1 fi # 运行程序 cd "$PROJECT_PATH" source .venv/bin/activate # 激活 uv 虚拟环境 python ollama_mcp_server.py "$@"

然后设置脚本权限：

chmod +x ollama-mcp-cli

注意：Windows 用户需要创建 ollama-mcp-cli.bat 文件，内容相应调整。

2. 在 Cursor 中配置

启动 Ollama 服务
在 Cursor 的 MCP 配置中，使用以下命令：

/完整路径/ollama-mcp-cli

提示：如果将脚本放在系统的可执行文件路径中（如 /usr/local/bin/），则可以直接使用脚本名称：
ollama-mcp-cli

3. 基本功能示例

⚠️ 本节待修改

查看可用模型：

result = await get_ollama_list()

简单对话：

response = await simple_chat( model="llama2", prompt="你好，请介绍一下自己" )

生成文本嵌入：

embeddings = await post_generate_embeddings( model="nomic-embed-text", text=["这是一段示例文本"] )

支持的功能与限制

API 端点支持状态

端点	方法	功能介绍	特性支持	工具名称
-	-	项目入门指南 💫 不想读枯燥的表格？让 AI 来帮你！尝试让你的 AI 助手运行	- 智能项目导航 ✨ - 个性化功能推荐 🎯 - 最佳实践指导 💡	`get_started_guide`
`/api/version`	GET	获取Ollama服务器版本	- 单次响应 ✅ - 包含构建信息 ✅	`get_ollama_version`
`/api/tags`	GET	获取已安装模型列表	- 完整响应 ✅ - 包含模型元数据 ✅	`get_ollama_list`
`/api/ps`	GET	查看运行中的模型	- 实时状态 ✅ - 资源使用数据 ✅	`get_running_models`
`/api/show`	POST	获取模型详细信息	- 详细模式 ✅ - 完整配置信息 ✅	`post_show_model`
`/api/chat`	POST	对话式交互功能	- 流式输出 ❌ - 多轮对话 ❌ - 系统提示词 ❌ - 图像输入 ❌	`simple_chat`
`/api/generate`	POST	基础文本生成	- 流式输出 ❌ - 上下文管理 ❌ - raw模式 ❌ - 模型JSON格式输出 ❌ - 工具JSON包装 ✅	`simple_generate`
`/api/embed`	POST	生成文本向量表示	- 批量处理 ✅ - 固定维度输出 ✅	`post_generate_embeddings`
`/api/embeddings`	POST	生成文本向量表示（已弃用）	- 批量处理 ✅ - 固定维度输出 ✅ - 已被 `/api/embed` 替代 ⚠️	`post_generate_embeddings`
`/api/copy`	POST	创建模型副本	- 原子操作 ❌ - 跨版本复制 ❌	未实现（管理员权限）
`/api/pull`	POST	下载并安装模型	- 进度反馈 ❌ - 断点续传 ❌ - 版本管理 ❌	未实现（管理员权限）
`/api/delete`	DELETE	移除指定模型	- 不可逆操作 ❌ - 释放资源 ❌	未实现（管理员权限）
`/api/create`	POST	创建新模型	- 模型创建 ❌ - 参数配置 ❌	未实现（管理员权限）
`/api/blobs/:digest`	HEAD	检查blob是否存在	- 二进制对象检查 ❌ - SHA256校验 ❌	未实现（管理员权限）
`/api/blobs/:digest`	POST	上传blob	- 二进制对象上传 ❌ - 大文件支持 ❌	未实现（管理员权限）

功能限制说明

基础功能限制
- 仅支持非流式响应（一次性返回结果）
- 不支持多轮对话历史
- 不支持系统提示词（system prompt）
- 不支持上下文管理
- 不支持 raw 模式和特定格式输出
管理功能限制
- 出于安全考虑，不支持以下管理员级别操作：
  - 模型复制（/api/copy）
  - 模型下载（/api/pull）
  - 模型删除（/api/delete）
- 配置文件中的 API 端点路径请勿随意修改
实验性功能
- 图片处理功能尚未完全实现和测试，不建议在生产环境使用
- 部分高级特性（如参数调优、模板定制）尚未实现