Skip to main content
Glama
Needle MCP Server

Needle MCP Server

Official
by needle-ai

使用 Needle MCP 服务器构建代理

铁匠徽章

特色截图 - 克劳德

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

目录


Related MCP server: Documentation MCP Server

概述

Needle MCP 服务器允许您:

  • 组织和存储文档以便快速检索。

  • 通过 Claude 的大型语言模型执行强大的搜索。

  • 与 Needle 生态系统无缝集成,实现高级文档管理。


特征

  • **文档管理:**轻松添加和组织服务器上的文档。

  • **搜索和检索:**基于 Claude 的自然语言搜索,快速获得答案。

  • **轻松集成:**可与Claude Desktop和 Needle 系列配合使用。


用法

Claude Desktop 中的命令

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

在 Claude Desktop 中使用命令

  1. 打开 Claude Desktop并连接到 Needle MCP 服务器。

  2. 使用简单的文本命令来搜索、检索或修改文档。

  3. 在用户友好的界面中查看 Claude 返回的搜索结果。

导致针

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


Youtube视频讲解

有关使用 Needle MCP Server 与 Claude 和 Claude Desktop 的完整演练,请观看此YouTube 解释视频。


安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Needle MCP:

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

手动安装

  1. 克隆存储库:

git clone https://github.com/yourusername/needle-mcp.git
  1. 在终端中使用 Homebrew 全局安装 UV:

brew install uv
  1. 创建claude_desktop_config.json:

    • 对于 MacOS:打开目录~/Library/Application Support/Claude/并在其中创建文件

    • 对于 Windows:打开目录%APPDATA%/Claude/并在其中创建文件

  2. 将此配置添加到claude_desktop_config.json:

{
  "mcpServers": {
    "needle_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}
  1. 从needle.xyz获取您的Needle API密钥

  2. 更新配置文件:

    • 将/path/to/needle-mcp替换为您的实际存储库路径

    • 添加您的 Needle API 密钥

  3. 彻底退出 Claude 并重新打开它

使用示例

  • “创建一个名为‘技术文档’的新集合”

  • “将此文档添加到集合中,即https://needle-ai.com ”

  • “在收藏中搜索有关人工智能的信息”

  • “列出我的所有收藏”

故障排除

如果不起作用:

  • 确保 UV 已全局安装(如果没有,请使用pip uninstall uv卸载,然后使用brew install uv重新安装)

  • 或者使用which uv查找 UV 路径,并将"command": "uv"替换为完整路径

  • 验证您的 Needle API 密钥是否正确

  • 检查配置中的needle-mcp路径是否与你的实际仓库位置匹配

重置 Claude 桌面配置

如果您看到的是旧配置或集成不起作用:

  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_mcp": {
      "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. 如果您仍然看到旧配置:

  • 检查其他位置的附加配置文件

  • 如果使用网页版,请尝试清除浏览器缓存

  • 验证配置文件是否从正确的位置读取

Available Tools

7 tools
needle_add_fileAInspect

Add a new document to a Needle collection by providing a URL for download. Supports multiple file formats including: - PDF documents - Microsoft Word files (DOC, DOCX) - Plain text files (TXT) - Web pages (HTML)

        The document will be:
        1. Downloaded from the provided URL
        2. Processed for text extraction
        3. Indexed for semantic search
        
        Use this tool when you need to:
        - Add new documents to a collection
        - Make documents searchable
        - Expand your knowledge base
        
        Important: Documents require processing time before they're searchable.
        Check processing status using needle_list_files before searching new content.

Inputs: collection_id (required), name (required), url (required).

needle_create_collectionAInspect

Create a new document collection in Needle for organizing and searching documents. A collection acts as a container for related documents and enables semantic search across its contents. Use this tool when you need to: - Start a new document organization - Group related documents together - Set up a searchable document repository Returns a collection ID that's required for subsequent operations. Choose a descriptive name that reflects the collection's purpose for better organization.

Inputs: name (required).

needle_get_collection_detailsAInspect

Fetch comprehensive metadata about a specific Needle collection. Provides detailed information about the collection's configuration, creation date, and current status. Use this tool when you need to: - Verify a collection's existence and configuration - Check collection metadata before operations - Get creation date and other attributes Requires a valid collection ID and returns detailed collection metadata. Will error if collection doesn't exist.

Inputs: collection_id (required).

needle_get_collection_statsAInspect

Retrieve detailed statistical information about a Needle collection's contents and status. Provides metrics including: - Total number of documents - Processing status of documents - Storage usage and limits - Index status and health Use this tool to: - Monitor collection size and growth - Verify processing completion - Check collection health before operations Essential for ensuring collection readiness before performing searches.

Inputs: collection_id (required).

needle_list_collectionsAInspect

List Needle collections. Returns maximum of 20 results. Get more results by increasing the offset. Returns detailed information including collection IDs, names, and creation dates. Use this tool when you need to: - Get an overview of available document collections - Find collection IDs for subsequent operations - Verify collection existence before performing operations The response includes metadata that's required for other Needle operations.

Inputs: offset.

needle_list_filesAInspect

List all documents stored within a specific Needle collection with their current status. Returns detailed information about each file including: - File ID and name - Processing status (pending, processing, complete, error) - Upload date and metadata Use this tool when you need to: - Inventory available documents - Check processing status of uploads - Get file IDs for reference - Verify document availability before searching Essential for monitoring document processing completion before performing searches.

Inputs: collection_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: collection management (create, list, get details, get stats), file management (add, list), and search. The descriptions explicitly differentiate their functions, such as needle_get_collection_details for metadata vs. needle_get_collection_stats for metrics, eliminating any ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with the 'needle_' prefix, using snake_case throughout (e.g., needle_create_collection, needle_list_files). This predictable naming scheme makes it easy for agents to understand and select tools based on their actions and targets.

    Tool Count5/5

    With 7 tools, the server is well-scoped for document management and search, covering essential operations like collection CRUD, file addition, status monitoring, and semantic search. Each tool serves a clear purpose without redundancy, fitting the domain's needs efficiently.

    Completeness4/5

    The toolset provides strong coverage for core document management workflows, including collection lifecycle, file processing, and search. A minor gap exists in file deletion or update capabilities, which could limit full CRUD operations, but agents can still perform key tasks like adding, listing, and searching documents effectively.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers