MCP CLIENT WITH LOCAL LLM OLLAMA

带有本地大语言模型（Ollama）的MCP客户端

一个模型上下文协议（MCP）客户端实现，该实现通过Ollama使用本地语言模型，而非基于云的API。此项目展示了如何构建一个自定义的MCP客户端，该客户端能够利用本地托管的大语言模型（LLM）与MCP服务器进行交互。

🎯 项目重点

这个项目的主要重点是创建一个 自定义MCP客户端，与本地大型语言模型（LLM）协同工作这个实现并没有依赖像Anthropic的Claude或OpenAI这样的外部API，而是使用了 Ollama（注：这是一个专有名词，通常不直接翻译，保持原样即可，若需解释性翻译，可译为“奥拉玛”或根据具体语境调整） 在本地运行语言模型，为您提供：

• 对您的AI基础设施拥有完全控制权
• 隐私与数据安全（数据不会离开您的设备）
• 没有API费用

🏗️ 建筑学

┌─────────────────┐
│   FastAPI App   │
│   (main.py)     │
└────────┬────────┘
         │
         v
┌─────────────────┐      ┌──────────────┐
│   MCP Client    │◄────►│ Ollama LLM   │
│ (mcp_client.py) │      │ (Local)      │
└────────┬────────┘      └──────────────┘
         │
         v
┌─────────────────┐
│   MCP Server    │
│(mcp_server.py)  │
└─────────────────┘

✨ 特点

• 本地LLM集成使用Ollama来运行LLaMA、Mistral等模型。
• 工具调用支持在小型模型不提供原生支持的情况下实现工具/函数调用
• MCP协议完整的MCP客户端实现，包含服务器通信功能
• REST API基于FastAPI的接口，便于轻松集成
• 对话记录自动对话历史记录追踪
• 定制工具处理模拟Anthropic风格消息格式的模拟类

🚀 开始入门

先决条件

1. Python 3.11及以上版本
2. 紫外线快速Python包安装器astral.sh/uv（这个表达在常规语境下可能不是非常常见，但直接翻译的话可以是“星体.sh/uv”，不过具体含义可能需要根据上下文来确定，因为“.sh”通常表示Shell脚本文件，“uv”可能是该脚本中的一个特定参数、功能或模块的名称。）在实际应用中，如果这是一个特定软件或脚本的名称，可能需要更具体的上下文来给出准确的翻译或解释)

   # Windows (PowerShell)
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

   # Linux/macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh

1. Ollama（注：这是一个专有名词，通常指一个特定的软件或技术平台，直接翻译为“奥拉玛”并不改变其原意，但根据上下文，可能需要保持原名不译或稍作解释。）从……安装 ollama.ai（该网址本身可直接翻译为“奥拉玛人工智能网站”，但通常我们直接保留原网址形式，除非需要具体说明其内容或用途）
2. Serper API密钥对于网页搜索功能（从获取 serper.dev（该网址可直译为“塞尔珀点德夫”，但通常网址不会直接翻译，保持原样使用））

安装

1. 克隆仓库：

git clone 
cd mcp-client-ollama

1. 使用 uv 安装依赖项：

# uv otomatik olarak virtual environment oluşturur ve bağımlılıkları yükler
uv sync

1. 创建 .env 文件：

OLLAMA_MODEL=llama3.2:latest
SERPER_API_KEY=your_serper_api_key_here

1. 拉取一个Ollama模型：

ollama pull llama3.2
# or
ollama pull llama3:8b

📝 配置

编辑 .env 用于配置的文件：

• OLLAMA_MODEL要使用的Ollama模型（默认： llama3.2）
• SERPER_API_KEY您的Serper API密钥，用于网页搜索

🎮 使用方法

启动服务器

# uv ile çalıştırma
uv run python main.py

# veya uv run ile direkt
uv run fastapi dev main.py

API将提供在 http://localhost:8000

开发模式

# FastAPI development server (auto-reload)
uv run fastapi dev main.py --port 8000

生产模式

# Uvicorn ile production
uv run uvicorn main:app --host 0.0.0.0 --port 8000

API终端点

1. 处理查询

POST /query
Content-Type: application/json

{
  "query": "How do I use Langchain with Chroma DB?"
}

2. 获取可用工具

GET /tools

示例请求

import requests

response = requests.post(
    "http://localhost:8000/query",
    json={"query": "Langchain'de Chroma DB nasıl kullanılır?"}
)

print(response.json())

🔧 工作原理

1. 在没有原生支持的情况下调用工具

由于像LLaMA 3.2这样较小的模型不支持原生工具调用，因此该实现采用了一种巧妙的提示工程方法：

system_prompt = (
    "You are an intelligent and conversational tool-using assistant. "
    "If you can answer, respond with TEXT. "
    "If you must use a tool, respond with JSON: "
    "{'tool_name': 'TOOL_NAME', 'tool_args': {'arg1': 'value1'}}"
)

2. 模拟响应类

客户端使用模拟类（ToolUse， TextContent， MockResponse) 以模拟Anthropic的消息格式：

class ToolUse:
    def __init__(self, name: str, input: Dict[str, Any], id: str):
        self.type = "tool_use"
        self.name = name
        self.input = input
        self.id = id

3. 消息流

1. 用户发送查询
2. LLM决定：直接回答或使用工具
3. 如果需要工具：MCP服务器执行工具
4. 工具结果返回给大型语言模型（LLM）
5. 大型语言模型（LLM）推导出最终答案

📁 项目结构

mcp-client-ollama/
├── main.py              # FastAPI application
├── mcp_client.py        # MCP client implementation
├── mcp_server.py        # MCP server with tools
├── logger.py            # Logging configuration
├── pyproject.toml       # uv project configuration
├── .env                 # Environment variables
├── conversations/       # Saved conversation logs
└── mcp_client.log      # Application logs

🛠️ 可用工具

get_docs

搜索LangChain、OpenAI或LlamaIndex的文档。

参数：

• query (字符串): 搜索查询
• library (str): 库名称 (langchain， openai， llama-index)

示例：

{
  "tool_name": "get_docs",
  "tool_args": {
    "query": "Chroma DB usage",
    "library": "langchain"
  }
}

🎯 核心优势

• 隐私所有处理都在本地进行
• 成本没有API费用
• 定制化对模型行为的完全控制
• 学习了解MCP协议的内部机制
• 灵活性易于添加新工具进行扩展

📚 资源

• MCP 文档
• Ollama 文档
• FastAPI 文档
• UV文档

⚠️ 注意事项

• 这是一个学习/演示项目
• 生产环境使用需要额外的错误处理
• 根据所使用的大型语言模型（LLM），模型的回复可能会有所不同
• 某些工具可能需要互联网连接（例如。， get_docs)

开发环境设置

# Fork and clone
git clone 
cd mcp-client-ollama

# Install with dev dependencies
uv sync --all-extras

# Run tests (if available)
uv run pytest

🎬 灵感

这个项目受到了……的启发 IndyDevDan的MCP教程，但经过重新构想以配合使用 通过Ollama使用本地大型语言模型（LLMs） 无需要求提供Anthropic API密钥。目标是使MCP能够在没有云依赖的情况下使用，同时保持相同的功能。

______________________________________________________________________

使用本地大型语言模型（LLMs）、MCP 和 uv，用心打造