使用说明

项目简介

JANHMS_needle-mcp-server 是一个 MCP 服务器实现，旨在桥接 LLM 应用（如 Claude）和 Needle 知识库服务。通过此服务器，LLM 应用可以方便地管理文档集合，并将文档内容用于增强对话的上下文理解和信息检索能力。简单来说，它让你的 Claude 可以理解和搜索你存储在 Needle 知识库中的文档。

主要功能点

文档集合管理：允许创建、查看和管理文档集合，方便用户组织和分类知识库。
文档添加：支持通过 URL 向指定集合添加文档，扩展知识库的内容。
语义搜索：提供在文档集合中进行语义搜索的功能，帮助 LLM 应用快速找到相关信息。
工具集成：以 MCP 工具的形式暴露上述功能，方便 LLM 客户端调用和集成。

安装步骤

克隆仓库

git clone https://github.com/MCP-Mirror/JANHMS_needle-mcp-server.git
cd JANHMS_needle-mcp-server

安装 UV (如果尚未安装) 根据仓库 'README.md' 的指引，推荐使用 Homebrew 安装 UV。
```
brew install uv
```
如果已经安装了 UV，可以跳过此步骤。如果未使用 Homebrew，请根据 UV 官方文档进行安装。
配置 Claude Desktop (如果使用 Claude Desktop) 如果希望将此 MCP 服务器与 Claude Desktop 客户端一起使用，需要创建或修改 Claude Desktop 的配置文件 'claude_desktop_config.json'。
- 查找配置文件位置
  - MacOS: '~/Library/Application Support/Claude/'
  - Windows: '%APPDATA%/Claude/'
- 创建或编辑 'claude_desktop_config.json' 在该目录下创建或编辑 'claude_desktop_config.json' 文件，并添加以下配置信息。

服务器配置

MCP 客户端（例如 Claude Desktop）需要配置 MCP 服务器的启动命令才能连接。以下是针对 'JANHMS_needle-mcp-server' 的 Claude Desktop 客户端配置示例：

{
  "mcpServers": {
    "needle_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/JANHMS_needle-mcp-server",  //  请替换为 JANHMS_needle-mcp-server 仓库在您本地的实际路径
        "run",
        "src/needle_mcp/server.py" //  指定运行服务器的 Python 脚本
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key" // 请替换为您的 Needle API 密钥
      }
    }
  }
}

配置参数说明:

'"needle_mcp"': 服务器名称，可以自定义，在 Claude Desktop 中用于标识和选择该服务器。
'"command": "uv"': 指定用于启动服务器的命令。这里使用 'uv'，确保已正确安装并添加到系统 PATH 环境变量中。如果 'uv' 不在 PATH 中，需要提供 'uv' 的完整路径。
'"args"': 启动服务器命令的参数列表。
- '"--directory"': 指定工作目录为 'JANHMS_needle-mcp-server' 仓库的根目录。请务必将 '/path/to/JANHMS_needle-mcp-server' 替换为您本地仓库的实际绝对路径。
- '"run"': 'uv run' 命令用于运行 Python 脚本。
- '"src/needle_mcp/server.py"': 指定要运行的 Python 脚本是 'src/needle_mcp/server.py'，这是 MCP 服务器的入口点。
'"env"': 环境变量配置。
- '"NEEDLE_API_KEY"': 请将 '"your_needle_api_key"' 替换为您在 Needle 官网获取的 API 密钥。 这是访问 Needle 服务的凭证，务必正确配置。

配置完成后，保存 'claude_desktop_config.json' 文件，并重启 Claude Desktop 客户端，配置即可生效。

基本使用方法

配置完成后，在 Claude Desktop 中，您可以使用自然语言指令来调用 Needle MCP 服务器提供的工具，例如：

创建集合: "Create a new collection called '技术文档'"
添加文档: "Add this document to the collection, which is https://example.com/document.pdf"
搜索文档: "Search the '技术文档' collection for information about人工智能"
列出集合: "List all my collections"

具体的指令可能需要参考 Claude Desktop 或其他 MCP 客户端的应用文档，根据其对工具的调用方式进行操作。

注意: 本仓库是 MCP 服务器的实现，主要用于后端部署。用户通常不需要直接操作服务器代码，而是通过 MCP 客户端（如 Claude Desktop）与其交互。

关键词