Local LLM MCP Tool

本地LLM MCP工具

  

完全在您的计算机上运行Llama模型的本地MCP（模型上下文协议）服务器。没有API密钥，没有云成本，100%私有和离线功能。

✨ 特性

• 🚀 100%本地 -所有推理都在你的CPU/GPU上运行，没有数据离开你的机器
• 🔒 私人 -您的对话将保留在您的设备上
• 💰 自由 -没有API成本或使用限制
• 🛠️ 多种工具 - generate_text, chat, complete, read_file, analyze_file，以及通过MCP进行会话管理
• 💬 对话历史和会话 -具有自动历史修剪功能的持久会话管理，以最大限度地减少存储
• 📡 流媒体支持 -可选增量令牌流，以实现更快的响应显示
• 🪟 Windows优化 -包括预制车轮和安装脚本
• 🔌 光标兼容 -与Cursor IDE无缝协作
• 🌌 反重力兼容 -与谷歌的Antigravity AI助手进行原生集成

🆕 最近添加的内容

• 对话历史和会话：使用自动历史管理创建持久对话会话。会话将消息存储在 history/ 具有可配置限制的文件夹，以最大限度地减少存储使用。
• 流媒体响应：启用增量令牌流，以获得更快的感知响应时间。通过环境变量配置块大小并启用/禁用。

📋 需求

• Python 3.10或更高版本
• Windows 10/11（即将支持Linux/Mac）
• GGUF格式的Llama模型（可自动下载）

🚀 快速开始

1.克隆存储库

git clone https://github.com/Marcel-MSC/local-llm-mcp-tool.git
cd local-llm-mcp-tool

2.安装依赖项

pip install -r requirements.txt

3.安装llama cpp python

对于Windows，使用预构建的轮子（推荐）：

选项A：仅CPU

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

选项B:NVIDIA GPU（性能更好）

pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121

或者使用自动安装程序：

PowerShell：

.\scripts\install_llama.ps1

CMD/批次：

scripts\install_llama.bat

⚠️ 注： 如果遇到编译错误，请参阅 WINDOWS_安装.md 用于故障排除。您还可以安装Visual Studio生成工具，以便从源代码进行编译。

4.配置模型

copy .env.example .env

编辑 .env 并设置模型路径：

MODEL_PATH=C:\path\to\your\model.gguf

5.下载模型（如果需要）

python scripts/download_model.py

或从以下网址手动下载 拥抱脸 并更新 MODEL_PATH 在 .env.

6.测试设置

python scripts/test_server.py

7.运行服务器

python server.py

或者使用FastMCP版本（更简单）：

python server_fastmcp.py

🔧 配置

环境变量(.env)

与Cursor IDE一起使用

1. 打开光标设置(Ctrl+,)
2. 搜索“MCP”或编辑 settings.json 直接
3. 添加配置：

{
  "mcpServers": {
    "local-llm": {
      "command": "python",
      "args": [
        "C:\\path\\to\\local-llm-mcp-tool\\server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

或者使用项目特定的配置： 创建 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "local-llm": {
      "command": "python",
      "args": [
        "C:\\path\\to\\local-llm-mcp-tool\\server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

1. 重新启动游标
2. 服务器将出现在 工具和MCP → 已安装的MCP服务器

使用反重力

Antigravity原生支持模型上下文协议。您可以使用提供的配置示例轻松连接本地模型 antigravity_mcp.json.example.

有关详细说明，请参阅 反重力集成指南.

🛠️ 可用工具

服务器公开了几个MCP工具：

1. generate_text

使用本地Llama模型生成文本。

参数：

• prompt （必填）：文本提示
• max_tokens （可选，默认值：256）：要生成的最大令牌数
• temperature （可选，默认值：0.7）：采样温度（0.0-2.0）
• top_p （可选，默认值：0.9）：Top-p采样（0.0-1.0）

2. chat

使用基于消息的格式与模特聊天。

参数：

• messages （必填）：消息数组 [{"role": "user", "content": "..."}]
• max_tokens （可选，默认值：256）：要生成的最大令牌数
• temperature （可选，默认值：0.7）：采样温度

3. complete

完成文本提示。

参数：

• text （必填）：待完成的文本
• max_tokens （可选，默认值：128）：要生成的最大令牌数
• temperature （可选，默认值：0.7）：采样温度

4. read_file

从MCP服务器的项目目录读取本地文本文件。从包含以下内容的目录解析相对路径 server.py。访问仅限于该目录树（否 ../.. 遍历）。

参数：

• path （必填）：文件路径（相对于服务器根目录）
• max_bytes （可选，默认值：200000）：要读取的最大字节数（防止大量读取）
• encoding （可选，默认值： "utf-8")：用于解码文件字节的文本编码

5. analyze_file

阅读本地文本文件，并要求本地Llama模型对其进行分析（目的、结构、问题、改进）。

参数：

• path （必填）：文件路径（相对于服务器根目录）
• instruction （可选）：自定义分析说明（例如“关注安全”、“用3个项目符号总结”）
• max_bytes （可选，默认值：200000）：从文件读取的最大字节数
• encoding （可选，默认值： "utf-8")：文件编码
• max_tokens （可选，默认值：512）：分析响应的最大令牌数
• temperature （可选，默认值：0.3）：用于分析的采样温度

6. start_session

开始新的对话会话并返回 session_id.此组 在保持CPU和磁盘使用率有限的同时，将多个回合放在一起。

参数：

• metadata （可选）：具有元数据的JSON对象，如 purpose, label等等。

7. continue_session

通过添加新用户消息继续现有会话。服务器加载 仅显示上下文的最新消息（受环境变量限制） 以避免CPU和存储的大量使用。

参数：

• session_id （必填）：返回的ID start_session.
• message （必填）：新用户消息。
• max_tokens （可选，默认值：256）：要生成的最大令牌数。
• temperature （可选，默认值：0.7）：采样温度。
• top_p （可选，默认值：0.9）：Top-p采样。

8. end_session

将会话标记为已结束，并可选择从磁盘中删除其历史记录。

参数：

• session_id （必填）：要结束的会话的ID。
• delete （可选，默认值： false)：是否删除存储的历史记录。

📚 使用示例

在光标聊天中

基本文本生成：

Use the generate_text tool from local-llm with prompt: Write a short sentence about programming.

通过消息聊天：

Use the chat tool from local-llm with messages: [{"role": "user", "content": "What is Python?"}]

从磁盘读取文件（返回文件文本）：

Use the read_file tool from local-llm with:
path: README.md

从磁盘分析文件（服务器读取文件，LLM对其进行分析）：

Use the analyze_file tool from local-llm with:
path: server.py
instruction: Summarize the main components and list 3 improvements.

“使用generate_text并阅读README.md+server.py”（两步工作流程）：

1. 读取每个文件（每个文件一次工具调用）：

Use the read_file tool from local-llm with:
path: README.md

Use the read_file tool from local-llm with:
path: server.py
max_bytes: 200000

1. 然后打电话 generate_text 在聊天上下文中使用上面显示的文件内容：

Use the generate_text tool from local-llm with prompt: Compare the README and server.py content above. Are the documented tools accurate? List any mismatches and propose README fixes.

使用对话会话：

1. 启动会话：

Use the start_session tool from local-llm with metadata: {"label": "coding-help"}

1. 继续对话（使用步骤1中的session_id）：

Use the continue_session tool from local-llm with:
session_id: abc123...
message: How do I create a Python function?

1. 使用相同的session_id继续发送更多消息以维护上下文。

1. 完成后结束会话：

Use the end_session tool from local-llm with:
session_id: abc123...
delete: false

程序化使用

看 scripts/example_usage.py 以Python为例。

🎯 推荐型号

任何GGUF格式的Llama兼容模型都可以使用。推荐：

• Llama 3.2 1B -重量轻、速度快、对CPU有好处
• Llama 3.1 8B -性能/质量平衡
• 米斯特拉尔7B -备选方案

下载地址： 拥抱脸GGUF模型

💬 对话历史和会话

服务器支持 持续对话会话 它们在多个交互中保持上下文，同时最大限度地减少存储和CPU使用。

会话如何工作

1. 启动会话 使用 start_session 获得独一无二的 session_id
2. 继续对话 使用 continue_session 同样的 session_id 保持上下文
3. 历史记录已存储 在 history/ 文件夹（一个 .jsonl 每个会话的文件）
4. 自动微调 仅保留最新消息（可配置限制）
5. 结束会话 随着 end_session 完成后（可选择删除历史记录）

存储管理

• 历史文件存储在 history/.jsonl （以行分隔的JSON）
• 会话元数据在中跟踪 history/sessions_index.json
• 自动修剪可防止无限生长：

- 每个会话的最大消息数（默认值：40） - 每个会话的最大文件大小（默认值：~2MB）

• 这 history/ 默认情况下，文件夹被忽略

配置

请参阅 环境变量 上表显示了会话相关设置：

• SESSION_HISTORY_DIR：历史文件的存储位置
• SESSION_MAX_MESSAGES：每个会话要保留多少条消息
• SESSION_MAX_FILE_BYTES：修剪前的最大文件大小
• SESSION_AUTO_TRIM：启用/禁用自动修剪

会话流示例

# 1. Start session
session_id = start_session(metadata={"label": "coding-help"})

# 2. Continue conversation (maintains context)
response1 = continue_session(session_id, "What is Python?")
response2 = continue_session(session_id, "How do I create a function?")  # Remembers previous context

# 3. End session
end_session(session_id, delete=False)  # Keep history, or delete=True to remove

📡 流媒体响应

服务器支持 可选流媒体 以获得更快的响应显示。启用后，令牌在生成时会逐步发送，而不是等待完整的响应。

启用流媒体

集 STREAMING_ENABLED=true 在你的 .env 文件：

STREAMING_ENABLED=true
STREAMING_CHUNK_SIZE=50

• STREAMING_ENABLED：启用/禁用流媒体（默认值： false)
• STREAMING_CHUNK_SIZE：每个块的近似字符数（默认值： 50).较小的值=更新更频繁，但开销略高。

运作原理

启用流媒体时：

• generate_text, chat, complete，以及 continue_session 工具返回多个 TextContent 块
• 每个块包含生成文本的一部分
• 客户端（光标）可以在文本到达时增量显示文本
• 对于 continue_session，流式传输完成后，完整的累积文本仍将保存到会话历史记录中

业绩说明

• 流媒体增加了最小的CPU开销（只是分块逻辑）
• 回应 质量 不变-流媒体仅影响 交货时间
• 在速度较慢的机器上，考虑使用启用流媒体的较小型号（1B-3B），以获得最佳体验
• 流媒体同时支持CPU和GPU推理

禁用流媒体

集 STREAMING_ENABLED=false （或省略它）在单个块中返回与原始行为匹配的完整响应。

🐛 故障排除

错误：“找不到模型”

• 验证 MODEL_PATH 在 .env 是正确的
• 在Windows上使用绝对路径
• 确保 .gguf 文件存在

错误：“未安装llama cpp python”

• 安装方式： pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
• 对于GPU： pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu121

服务器未出现在游标中

• 检查MCP配置中的路径
• 使用带有双反斜杠的绝对路径(\\)或正斜杠
• 添加配置后重新启动Cursor
• 检查光标的输出面板（MCP日志）是否有错误

性能缓慢

• 使用较小的型号（1B-3B）进行仅CPU设置
• 集 N_GPU_LAYERS=-1 在 .env 如果你有NVIDIA GPU
• 调整 N_THREADS 以匹配您的CPU内核
• 减少 CONTEXT_SIZE 如果你不需要冗长的上下文

Windows上的编译错误

• 看 安装_编译器_WINDOWS.md 用于安装Visual Studio生成工具
• 或使用预制车轮（推荐）

📁 项目结构

local-llm-mcp-tool/
├── server.py              # Main MCP server (standard API)
├── server_fastmcp.py      # Alternative server (FastMCP, simpler)
├── scripts/               # Helper and setup scripts
│   ├── download_model.py      # Model download helper
│   ├── example_usage.py       # Usage examples
│   ├── install_llama.bat      # Batch installer
│   ├── install_llama.ps1      # PowerShell installer
│   ├── suggest_model.py       # Script to suggest a model based on hardware
│   └── test_server.py         # Setup test script
├── requirements.txt       # Python dependencies
├── .env.example          # Configuration template
├── .gitignore           # Git ignore rules
└── README.md            # This file

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📝 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

• llama.cpp -核心推理机
• llama cpp python -Python绑定
• 模型上下文协议 -MCP规范
• 光标 -使其有用的IDE

🔮 未来想法

看 FUTURE_IDEAS.md 对于计划中的功能：

• ✅ ~~对话历史/会话~~- 已实施！
• ✅ ~~流媒体响应~~- 已实施！
• RAG（文件问答）
• 多型号支持
• 长对话的会话摘要
• 还有更多。..

______________________________________________________________________

制作❤️ 对于那些希望在没有云的情况下使用本地AI的注重隐私的开发人员来说。