Needle MCP Server

官方

开箱即用的生产级RAG，用于搜索和检索自有文档中的数据。

GitHub
99

文档

使用 Needle MCP Server 构建智能代理

smithery badge

Screenshot of Feature - Claude

MCP（模型上下文协议）服务器，用于通过 Claude 桌面应用程序管理文档并使用 Needle 执行搜索。

Needle Server MCP server

目录

概述

Needle MCP Server 允许您：

  • 整理和存储文档以便快速检索。
  • 通过 Claude 的大语言模型执行强大的搜索。
  • 与 Needle 生态系统无缝集成，实现高级文档管理。

MCP（模型上下文协议）标准化了 LLM 连接外部数据源的方式。您可以使用 Needle MCP Server 轻松在 AI 应用中启用语义搜索工具，让隐藏在 PDF、DOCX、XLSX 和其他文件中的数据可被 LLM 即时访问。

我们建议使用远程 MCP 服务器以获得最佳体验——无需本地设置。

功能特性

  • 文档管理： 轻松在服务器上添加和整理文档。
  • 搜索与检索： 基于 Claude 的自然语言搜索，快速获取答案。
  • 轻松集成： 与 Claude Desktop 和 Needle 集合配合使用。

使用方法

Claude Desktop 中的命令

以下是如何在 Claude Desktop 中使用命令与服务器交互的示例：

Using commands in Claude Desktop

  1. 打开 Claude Desktop 并连接到 Needle MCP Server。
  2. 使用简单的文本命令来搜索、检索或修改文档。
  3. 查看 Claude 返回的搜索结果，界面友好。

Needle 中的结果

https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c

YouTube 视频讲解

有关将 Needle MCP Server 与 Claude 和 Claude Desktop 结合使用的完整演示，请观看此 YouTube 讲解视频。

安装

1. 远程 MCP 服务器（推荐）

Claude Desktop 配置

创建或更新您的配置文件：

  • 对于 MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • 对于 Windows：%APPDATA%/Claude/claude_desktop_config.json
{
  "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>"
      }
    }
  }
}

Cursor 配置

创建或更新 .cursor/mcp.json：

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

从 Needle 设置 获取您的 API 密钥。

我们提供两个端点：

  • 流式 HTTP：https://mcp.needle.app/mcp（推荐）
  • SSE：https://mcp.needle.app/sse

注意：MCP 在最新规范中已弃用 SSE 端点，因此较新的客户端应优先使用流式 HTTP 端点。

2. 本地安装

  1. 克隆仓库：
git clone https://github.com/needle-ai/needle-mcp.git
  1. 使用 Homebrew 全局安装 UV：
brew install uv
  1. 创建您的配置文件：
    • 对于 MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
    • 对于 Windows：%APPDATA%/Claude/claude_desktop_config.json

Claude Desktop 配置

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

Cursor 配置

{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": ["--directory", "/path/to/needle-mcp", "run", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}
  1. 将 /path/to/needle-mcp 替换为您的实际仓库路径
  2. 添加您的 Needle API 密钥
  3. 重启 Claude Desktop

通过 Smithery 安装

npx -y @smithery/cli install needle-mcp --client claude

3. Docker 安装

  1. 克隆并构建：
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .
  1. 添加到您的 Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）：
{
  "mcpServers": {
    "needle": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}
  1. 重启 Claude Desktop

使用示例

  • "创建一个名为'技术文档'的新集合"
  • "将此文档添加到集合中，即 https://needle.app"
  • "在集合中搜索关于 AI 的信息"
  • "列出我的所有集合"

故障排除

如果无法正常工作：

  • 确保 uv 已全局安装（如果没有，请使用 pip uninstall uv 卸载，然后使用 brew install uv 重新安装）
  • 或者使用 which uv 查找 uv 路径，并将 "command": "uv" 替换为完整路径
  • 验证您的 Needle API 密钥是否正确
  • 检查配置中的 needle-mcp 路径是否与您的实际仓库位置匹配

重置 Claude Desktop 配置

如果您看到旧配置或集成无法正常工作：

  1. 查找所有 Claude Desktop 配置文件：
find / -name "claude_desktop_config.json" 2>/dev/null
  1. 删除所有 Claude Desktop 数据：
  • 在 MacOS 上：rm -rf ~/Library/Application\ Support/Claude/*
  • 在 Windows 上：删除 %APPDATA%/Claude/ 的内容
  1. 创建一个仅包含 Needle 的全新配置：
mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json
<< 'EOL'
{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}
EOL

  1. 完全退出 Claude Desktop（Mac 上使用 Command+Q）并重新启动

  2. 如果仍然看到旧配置：

  • 检查其他位置是否有额外的配置文件
  • 如果使用网页版，尝试清除浏览器缓存
  • 验证配置文件是否从正确的位置读取