needle-mcp

你是否曾经想过让 AI 助手拥有长期记忆？你是否希望 Claude 能够记住你们上周讨论过的项目细节，或者从你上传的几十份 PDF 文档中快速找到答案？传统的对话模型受限于上下文窗口长度，无法在每次对话中都保留全部历史信息。

这就是 needle-mcp 要解决的核心问题。它是一个基于模型上下文协议的服务器，连接了 Needle 平台——一个专门为大型语言模型提供长期记忆和 RAG 能力的服务。通过这个服务器，你可以让 Claude 等 AI 助手能够创建文档集合、添加内容、并进行语义搜索，从而实现跨越多次对话的“记忆”。

项目基本信息

一、项目介绍

needle-mcp 是一个 MCP 服务器，它充当了 AI 客户端与 Needle 平台之间的桥梁。Needle 本身是一个文档管理和语义搜索平台，专门解决 LLM 的“内存不足”问题。你可以把 Needle 理解为 AI 的“外部硬盘”——你可以随时存入文档，也可以随时通过自然语言搜索找到相关内容。

通过这个服务器，你可以让 AI 助手执行以下操作：

• 创建和管理文档“集合”（Collection），类似于文件夹。
• 向集合中添加文档（支持 PDF、DOCX、XLSX、网页链接等）。
• 在集合中进行语义搜索，找到与问题最相关的片段。
• 列出所有已有的集合。

该服务器提供了两种使用模式：一种是推荐使用的远程 MCP 服务器，无需本地安装，通过 Needle 的云端服务运行；另一种是本地安装，适合需要完全控制或离线使用的场景。

二、核心优势

真正的长期记忆
与临时保存对话历史不同，Needle 存储的是经过向量化的、可检索的知识。你可以让 AI “记住”你公司所有的产品文档，并在未来的任何一次对话中回答相关问题。

开箱即用的 RAG 能力
RAG 是让 AI 从外部知识库中检索信息的能力。needle-mcp 把复杂的 RAG 管道封装成了简单的自然语言指令。你不需要关心分块、嵌入、向量数据库等概念。

无缝集成主流 AI 客户端
项目提供了详细的配置示例，支持 Claude Desktop、Cursor 等客户端。你可以继续使用你熟悉的 AI 工具，同时获得强大的外部记忆能力。

灵活的部署选项
无论你是想零配置使用远程服务，还是希望数据完全私有而选择本地 Docker 部署，needle-mcp 都提供了清晰的路径。

支持多种文档格式
不仅仅是纯文本，你可以添加 PDF、Word、Excel 文件，甚至是一个网页链接。服务器会自动处理内容的提取和向量化。

三、适用场景

企业知识库问答
创建名为“公司员工手册”的集合，上传所有 HR 文档。然后你可以问：“我们公司的年假政策是什么？” AI 会在集合中搜索并给出答案。

个人学习助手
为每门课程创建一个集合，上传课件 PDF 和笔记。复习时你可以问：“解释一下第 3 章提到的那个概念”，AI 会准确找到相关内容。

研发团队的文档中心
创建一个“API 文档”集合，上传所有内部接口文档。在开发时，你可以让 AI 根据最新的文档生成调用代码。

跨会话的记忆保持
你正在和 AI 讨论一个长期项目。每周你可以把最新进展的摘要存入 Needle。下周再次对话时，AI 可以“回忆起”上周的结论。

内容审核与合规
上传一批需要审查的文档，然后通过自然语言查询，如“找出所有提到‘竞品’这个词的段落”。

四、安装教程

needle-mcp 提供了三种安装方式。官方推荐使用远程 MCP 服务器，体验最佳且无需本地维护。以下是详细的配置步骤。

准备工作

你需要一个 Needle API 密钥。可以前往 Needle 平台的设置页面获取。

方法一：远程 MCP 服务器（推荐）

这是最简单的方式，不需要克隆代码或安装依赖。

第一步：配置 Claude Desktop

找到 Claude Desktop 的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

用文本编辑器打开，添加以下内容。请将 <your-needle-api-key> 替换为你的真实密钥。

{
  "mcpServers": {
    "needle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.needle.app/mcp",
        "--header",
        "Authorization:Bearer ${NEEDLE_API_KEY}"
      ],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

第二步：重启 Claude Desktop

完全退出应用（macOS 上使用 Cmd+Q），然后重新启动。右侧应能看到工具图标。

方法二：本地安装（使用 uv）

如果你希望代码和数据完全在本地运行，可以使用此方法。

第一步：克隆仓库并安装 uv

git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
brew install uv  # macOS 使用 Homebrew

第二步：配置 Claude Desktop

在配置文件中添加如下内容，请将 /path/to/needle-mcp 替换为你的实际路径。

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

第三步：重启 Claude Desktop。

方法三：Docker 安装

第一步：构建镜像

git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .

第二步：配置 Claude Desktop

{
  "mcpServers": {
    "needle": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

第三步：重启 Claude Desktop。

五、使用示例

假设你已经通过远程 MCP 服务器成功连接，以下是在 Claude 中的实际对话示例。

示例1：创建集合

用户输入：帮我创建一个名为“MCP 学习资料”的新集合。

Claude 会调用相关工具，然后回答：“好的，我已经创建了名为‘MCP 学习资料’的集合。”

示例2：向集合中添加文档

用户输入：把网页 https://modelcontextprotocol.io/introduction 添加到“MCP 学习资料”这个集合中。

Claude 会处理你的请求，并确认：“已成功添加该网页文档。”

示例3：搜索集合中的内容

用户输入：在“MCP 学习资料”集合中，搜索关于“resources”概念的解释。

Claude 会搜索集合中的所有文档，并返回最相关的结果片段，然后用自己的话总结给你听。

示例4：列出所有集合

用户输入：我现在有哪些集合？

Claude 会调用列表工具，返回类似：“您目前有两个集合：‘MCP 学习资料’和‘员工手册’。”

六、常见问题

问题1：配置后 Claude 中看不到 needle 工具图标。

解决方案：请确保你完全退出了 Claude Desktop 后，才修改配置文件。修改完成后，重新启动。如果还是不行，请检查 JSON 格式是否正确（特别是逗号和括号）。另外，可以尝试运行 which npx 确认 npx 是否在 PATH 中。

问题2：提示“认证失败”或“无效的 API 密钥”。

解决方案：确认你的 Needle API 密钥是有效的，并且没有过期。在配置文件中，请确保 Authorization:Bearer 和密钥之间没有多余空格。如果你使用的是远程配置，环境变量 ${NEEDLE_API_KEY} 会被正确替换吗？为了排除问题，你可以尝试直接在 args 中写死密钥（仅用于测试，注意安全）。

问题3：本地安装时提示 uv: command not found。

解决方案：这表示你没有安装 uv。请使用 brew install uv（macOS/Linux）或访问 uv 的官方文档进行安装。注意不要使用 pip install uv，因为作者在文档中特别提示这可能会造成问题。如果 brew 不可用，可以用 which uv 找到路径后，在配置中使用绝对路径。

问题4：我想清除所有 Claude Desktop 的 MCP 配置，如何重置？

解决方案：项目文档中提供了一个彻底重置的方法。首先退出 Claude Desktop。然后在终端中执行：

rm -rf ~/Library/Application\ Support/Claude/*

然后重新启动 Claude，它会像第一次启动一样创建一个干净的配置目录。之后再按照教程添加 needle 配置。

问题5：这个服务器和普通的 Needle 界面有什么区别？

解决方案：普通的 Needle 是一个 Web 应用，你需要手动上传文件、管理集合。而通过 MCP 服务器，你可以在与 AI 对话的过程中，用自然语言直接完成所有操作。AI 可以自主决定何时需要搜索记忆，何时需要存入新信息，实现了真正的“智能化记忆”。

七、总结

needle-mcp 是一个非常成熟的 MCP 生产级应用。它解决了当前 LLM 最痛点的问题之一：有限且昂贵的上下文窗口。通过将 Needle 强大的 RAG 能力以 MCP 协议的形式开放出来，它让任何支持 MCP 的 AI 客户端都能瞬间拥有“无限记忆”。

这个项目的亮点在于：

• 易用性：远程服务器模式真正做到了零配置，几分钟内即可上手。
• 灵活性：本地和 Docker 部署满足了对数据隐私有严格要求的用户。
• 生态整合：与 Claude Desktop、Cursor 等主流工具的深度集成，让它非常实用。

对于希望将 AI 应用于实际业务、构建基于文档的问答系统或智能助手的开发者来说，needle-mcp 是一个值得认真研究的工具。它不仅是一个 MCP 服务器，更是一种范式：让 AI 的记忆不再局限于当下的对话，而是可以跨越时间，持续积累。