Build Agents with Needle MCP Server

使用 Needle MCP 服务构建 Agent

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

目录

• 概述
• 功能
• 用法
  • Claude Desktop 中的命令
  • Needle 中的结果
• 安装
• 视频说明

---

概述

Needle MCP 服务可用于：

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

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

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

---

功能

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

---

用法

Claude Desktop 中的命令

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

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

Needle 中的结果

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

---

YouTube 视频说明

如需完整了解如何将 Needle MCP 服务与 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 Settings 获取 API 密钥。

我们提供两个端点：

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

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

2. 本地安装

1. 克隆仓库：

git clone https://github.com/needle-ai/needle-mcp.git

2. 使用 Homebrew 全局安装 UV：

brew install uv

3. 创建配置文件：
   • 对于 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>"
      }
    }
  }
}

4. 将 /path/to/needle-mcp 替换为实际的仓库路径
5. 添加 Needle API 密钥
6. 重启 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 .

2. 添加到 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>"
      }
    }
  }
}

3. 重启 Claude Desktop

使用示例

• “创建一个名为 ‘Technical Docs’ 的新集合”
• “将这份文档添加到集合，文档位于 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

2. 删除所有 Claude Desktop 数据：

• 在 MacOS 上：rm -rf ~/Library/Application\ Support/Claude/*
• 在 Windows 上：删除 %APPDATA%/Claude/ 中的内容

3. 创建仅包含 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

4. 完全退出 Claude Desktop（在 Mac 上按 Command+Q），然后重新启动

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

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