Skip to main content
Glama
Ollama_MCP_Guidance

Ollama_MCP_Guidance

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 Sample

使用环境

  • 本项目设计为 Cursor IDE 的 MCP 服务

  • 需要在 Cursor 中通过 MCP 协议调用

  • 不提供独立的客户端实现

安装

  1. 确保已安装 Python 3.10 或更高版本

  2. 安装 Ollama

  3. 安装项目:

# 安装 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 中配置

  1. 启动 Ollama 服务

  2. 在 Cursor 的 MCP 配置中,使用以下命令:

/完整路径/ollama-mcp-cli

提示:如果将脚本放在系统的可执行文件路径中(如 /usr/local/bin/),则可以直接使用脚本名称:

ollama-mcp-cli

3. 基本功能示例

⚠️ 本节待修改

  1. 查看可用模型:

result = await get_ollama_list()
  1. 简单对话:

response = await simple_chat(
    model="llama2",
    prompt="你好,请介绍一下自己"
)
  1. 生成文本嵌入:

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

支持的功能与限制

API 端点支持状态

端点

方法

功能介绍

特性支持

工具名称

-

-

项目入门指南💫 不想读枯燥的表格?让 AI 来帮你!尝试让你的 AI 助手运行 get_started_guide 工具吧!

- 智能项目导航 ✨- 个性化功能推荐 🎯- 最佳实践指导 💡

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

- 二进制对象上传 ❌- 大文件支持 ❌

未实现(管理员权限)

功能限制说明

  1. 基础功能限制

    • 仅支持非流式响应(一次性返回结果)

    • 不支持多轮对话历史

    • 不支持系统提示词(system prompt)

    • 不支持上下文管理

    • 不支持 raw 模式和特定格式输出

  2. 管理功能限制

    • 出于安全考虑,不支持以下管理员级别操作:

      • 模型复制(/api/copy)

      • 模型下载(/api/pull)

      • 模型删除(/api/delete)

    • 配置文件中的 API 端点路径请勿随意修改

  3. 实验性功能

    • 图片处理功能尚未完全实现和测试,不建议在生产环境使用

    • 部分高级特性(如参数调优、模板定制)尚未实现

依赖要求

  • Python >= 3.10

  • httpx >= 0.28.1

  • mcp[cli] >= 1.3.0

许可证

MIT License

💡 友好提示:如果您正在使用这个项目,欢迎通过邮件 (shadowsinger.tp@gmail.com) 告诉我。这不是必须的,但我很乐意知道这个项目对您有帮助!

<目前项目是面向cursor mcp的server项目,没有client,因此仅建议用于cursor mcp> <目前项目是中文项目,注释中包含中文和英文内容,将在未来的某一个版本将注释全部改为英文,并提供中文注释文件备份方便中文用户> <目前项目没有完全实现ollama支持的所有api端点>

<添加对于项目功能和未实现功能的说明: 1.目前项目不支持流式传输 2.目前项目不支持图片处理(尽管有相关代码,但未完全实现并测试) 3.目前项目没有完全实现ollama支持的所有api端点 4.关于实现的功能,请把notes.md最后的表格复制到此readme中进行说明。>

Available Tools

9 tools
get_api_doc_sectionD

Inputs: titles (required), max_length. Returns: result

get_ollama_listA

List all available models in the Ollama server.

This tool queries the Ollama API's /api/tags endpoint to retrieve information about
all available models, including both pulled models and their different tags.

Args:
    None: This function does not require any parameters.

Returns:
    str: JSON-formatted string containing:
        - List of available models with their details if successful
        - Error details if the request fails or response format is invalid

Inputs: no named parameters. Returns: result

get_ollama_versionA

Get the version information of the Ollama server.

This tool queries the Ollama API's /api/version endpoint to retrieve the server version.
It's useful for checking if the Ollama service is running and verifying its version.

Args:
    None: This function does not require any parameters.

Returns:
    str: JSON-formatted string containing:
        - Version information if successful
        - Error details if the request fails

Inputs: no named parameters. Returns: result

get_running_modelsA

Get the status of currently running Ollama models.

This tool queries the Ollama API's /api/ps endpoint to retrieve information about running models,
similar to the 'ollama ps' command. It validates the response format and provides formatted output.

Args:
    None: This function does not require any parameters.

Returns:
    str: JSON-formatted string containing:
        - List of running models with their details if successful
        - Error details if the request fails or response format is invalid

Inputs: no named parameters. Returns: result

get_started_guideA

🌟 Getting Started Guide: Your Gateway to the ask-ollama Project

⚠️ AI Assistant Note:
Before proceeding with any operations, it's highly recommended to:
1. Ask the user if they're new to the project
2. Explain that this guide will provide comprehensive understanding
3. Mention that this tool contains essential information for optimal project usage

Why this guide is essential for AI assistants:
1. Provides complete project overview and capabilities
2. Contains special instructions for AI-user interactions
3. Details recommended workflows and best practices
4. Lists all available tools with practical examples
5. Explains current limitations and workarounds
6. Includes API documentation navigation guide

This guide will help you:
- Better understand user requirements
- Make informed tool recommendations
- Navigate API documentation effectively
- Avoid common pitfalls
- Provide more accurate assistance

Remember: Running this guide first will significantly enhance your ability to assist users effectively.

Args:
    None: This function does not require any parameters.
    
Returns:
    str: JSON-formatted string containing comprehensive project documentation and usage guidelines.

Inputs: no named parameters. Returns: result

post_generate_embeddingsA

Generate embeddings for the given text using Ollama API.

Args:
    model (str): Model name to use for embeddings generation.
           Example: "nomic-embed-text"
    text (List[str]): List of texts to generate embeddings for.
           Example: ["Text 1"] or ["Text 1", "Text 2"]

Returns:
    str: JSON-formatted string containing:
        - Embeddings data and metadata if successful
        - Error details if the request fails or response format is invalid

Inputs: model (required), text (required). Returns: result

post_show_modelA

Show detailed information about a model.

This function retrieves detailed information about the specified model
through the Ollama API's /api/show endpoint.

Args:
    model (str): Model name, e.g., "llama2" or "mistral"

Returns:
    str: JSON-formatted model information including:
        - Basic info (family, parameter size, quantization)
        - Technical parameters (context length, layer count)
        - Configuration (template, system prompt)
        - License and modelfile content
        If the request fails, returns error information in JSON format.

Inputs: model (required). Returns: result

simple_chatA

Basic chat interaction with Ollama models.

This is a simplified chat implementation that provides basic conversation
capabilities without advanced features. For advanced features, please use
complex_chat (not implemented yet).

Limitations:
1. No conversation history (messages array)
2. No streaming support (stream)
3. No system prompts (system role)
4. No image input support (images)
5. No format control (format)
6. No parameter tuning (options)
7. No keep-alive control (keep_alive)

Features:
1. Basic chat: Single message and response
2. Error handling: Connection and format validation
3. Performance metrics: Processing time and token statistics

Args:
    model (str): Model name to use, e.g., "llama2", "mistral"
    prompt (str): User input text

Returns:
    str: JSON-formatted string containing:
        - Model response and metadata if successful
        - Error details if the request fails or response format is invalid

Inputs: model (required), prompt (required). Returns: result

simple_generateA

Basic text generation with Ollama models.

This is a simplified implementation of the /api/generate endpoint that provides
basic text generation capabilities without advanced features.

Limitations:
1. No streaming support
2. No raw mode
3. No format control
4. No parameter tuning (options)
5. No context management

Features:
1. Basic generation: Single prompt and response
2. Error handling: Connection and format validation
3. Performance metrics: Processing time and token statistics

Args:
    model (str): Model name to use, e.g., "llama2", "mistral"
    prompt (str): Text prompt for generation

Returns:
    str: JSON-formatted string containing:
        - Generated text and metadata if successful
        - Error details if the request fails

Inputs: model (required), prompt (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: listing models, version, running status, guide, embeddings, model info, chat, and generation. The `get_api_doc_section` tool lacks a description, creating slight ambiguity, and `simple_chat` vs `simple_generate` could be confused but descriptions mitigate this.

    Naming Consistency3/5

    Naming mixes prefixes: `get_*` for queries, `post_*` for actions, and `simple_*` for simplified implementations. While all use underscore_case, the inconsistent verb prefix and the `simple_` prefix deviate from a strict verb_noun pattern.

    Tool Count5/5

    9 tools is well-scoped for an Ollama MCP server focused on guidance and basic interactions. Each tool covers a distinct aspect without unnecessary overlap or excessive quantity.

    Completeness4/5

    The tool set covers core operations: listing, version, running status, embeddings, model info, chat, and generation. It lacks model management (pull, delete, create) but that aligns with a guidance focus. The `get_api_doc_section` tool hints at documentation access, enhancing completeness.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers