Needle

Provides an MCP server that manages documents and enables semantic Needle search through Claude chat.

javascript

0

GitHub Stars

javascript

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "mcp-mirror-janhms_needle-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}

Needle MCP Server lets you manage documents and perform semantic search through Claude chat by running a local MCP process that talks to Needle. You set up a small local wrapper that the Claude Desktop client can start and connect to, enabling seamless document collections and search across your Needle data.

How to use

You use the Needle MCP Server by starting the local MCP process and then connecting Claude Desktop to it. Create or join a collection in Needle, add documents you want to search, and then issue natural language queries like “Search for information about AI” to retrieve relevant results. You can create new collections, add documents via URLs, and run searches across your configured data. Ensure your Claude Desktop is configured to launch the Needle MCP Server at startup so every session can access your Needle data through the MCP endpoint.

How to install

Prerequisites you need before starting:

Install UV globally using Homebrew in Terminal:

Clone the project, install dependencies if needed, and configure Claude Desktop to run the MCP server.

# Step 1: Install UV globally
brew install uv

# Step 2: Clone the project (adjust URL to your actual repo)
git clone https://github.com/yourusername/needle-mcp.git

# Step 3: Create the Claude Desktop config (details below)

Configuration and runtime details

You will run the MCP server via a local command with an environment variable for the Needle API key. The configuration example shows how Claude Desktop should start the MCP process.

{
  "mcpServers": {
    "needle_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}

Available tools

Document management

Create and organize document collections in Needle, attach documents via URLs, and prepare data for semantic search.