Needle MCP Server

How to use

Connect your Claude Desktop client to the Needle MCP Server to enable semantic search and document retrieval. Once connected, you can issue plain-language queries such as “Search for information on AI” or “List documents in the Technical Docs collection,” and Claude will fetch and present relevant results from Needle. You can also manage collections and documents through simple text commands in Claude Desktop, and review the results directly in the Claude interface.

How to install

Prerequisites you should have before starting:

• Node.js and npm are available for running MCP-related tooling via npx.
• A tool for running local MCP servers, such as uv, may be used for a stdio-based workflow.

1) Remote MCP Server (recommended) This setup connects Claude Desktop to Needle’s hosted MCP endpoint. Use the following configuration blocks in Claude Desktop and Cursor so Claude can reach the remote server.

{
  "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>"
      }
    }
  }
}

{
  "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>"
      }
    }
  }
}

Get your API key from Needle Settings. The remote endpoints are: - Streamable HTTP: https://mcp.needle.app/mcp - SSE: https://mcp.needle.app/sse Note: MCP deprecated SSE endpoints in the latest specification, so newer clients should prefer the Streamable HTTP endpoint.

2) Local Installation

If you prefer running the MCP server locally, follow these steps to install and run Needle MCP using UV.

# 1) Clone the repository
git clone https://github.com/needle-ai/needle-mcp.git

# 2) Install UV globally (on macOS via Homebrew)
brew install uv

# 3) Create your Claude Desktop config (MacOS example)
#   The exact path depends on your OS
#   MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
#   Windows: %APPDATA%/Claude/claude_desktop_config.json

Then add a local stdio MCP entry to Claude Desktop config to run Needle MCP from your local copy.

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

If you use the Cursor config, mirror the same settings there so the cursor can access the local server.

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

4) Replace /path/to/needle-mcp with your actual repository path and add your Needle API key. Then restart Claude Desktop to apply changes.

5) Installing via Smithery (optional) You can install the MCP server client as a Smithery package if you prefer.

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

3) Docker Installation

If you want to run Needle MCP inside Docker, follow these steps to build and configure it with Claude Desktop.

# Build the container
git clone https://github.com/needle-ai/needle-mcp.git
cd needle-mcp
docker build -t needle-mcp .

# Add to Claude Desktop config to run the container

Then restart Claude Desktop to enable the Docker-based MCP server. You can configure the Claude Desktop MCP entry to run the container with similar environment variables as shown in the local setup.

Troubleshooting

If something isn’t working, try these steps: - Ensure uv is installed globally if you are using the local stdio workflow. If needed, reinstall uv: brew install uv. - If uv cannot be found, determine its full path with which uv and use the full path in your config. - Verify your Needle API key is correct and present in the environment variables for your MCP entry. - Confirm the needle-mcp path in your local config matches your actual repository location.

If you need a reset of Claude Desktop configuration, follow these steps to remove old data and apply a fresh config.

# 1) Find Claude Desktop config files
find / -name "claude_desktop_config.json" 2>/dev/null

# 2) Remove Claude Desktop data (caution: this resets all settings)
# MacOS
rm -rf ~/Library/Application\ Support/Claude/*
# Windows
# Delete contents of %APPDATA%/Claude/

3) Create a fresh config that uses Needle only and restart Claude Desktop.

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

4) Fully quit Claude Desktop (Command+Q on Mac) and relaunch it.

5) If old configurations persist, search for additional config files in other locations, or clear the browser cache if you use the web version, and ensure the config file path Claude Desktop reads from is correct.

Notes and considerations

This MCP setup focuses on connecting Claude Desktop to Needle’s hosted or local MCP server to enable semantic search and document management workflows. To maximize security, protect your API keys and do not share them in shared environments. Use the remote endpoint for the easiest setup, or run locally if you need an isolated environment.

document_management

Manage, organize, and store documents on the MCP server for quick retrieval and semantic search.

search_retrieval

Perform Claude-based natural language searches to retrieve relevant documents and snippets from Needle collections.