Content
# Build Agents with Needle MCP Server

MCP (Model Context Protocol) server to manage documents and perform searches using [Needle](https://needle-ai.com) through Claude’s Desktop Application.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Usage](#usage)
- [Commands in Claudie Desktop](#commands-in-claudie-desktop)
- [Result in Needle](#result-in-needle)
- [Installation](#installation)
- [Video Explanation](#youtube-video-explanation)
---
## Overview
Needle MCP Server allows you to:
- Organize and store documents for quick retrieval.
- Perform powerful searches via Claude’s large language model.
- Integrate seamlessly with the Needle ecosystem for advanced document management.
---
## Features
- **Document Management:** Easily add and organize documents on the server.
- **Search & Retrieval:** Claude-based natural language search for quick answers.
- **Easy Integration:** Works with [Claudie Desktop](#commands-in-claudie-desktop) and Needle collections.
---
## Usage
### Commands in Claudie Desktop
Below is an example of how the commands can be used in Claudie Desktop to interact with the server:

1. **Open Claudie Desktop** and connect to the Needle MCP Server.
2. **Use simple text commands** to search, retrieve, or modify documents.
3. **Review search results** returned by Claude in a user-friendly interface.
### Result in Needle
https://github.com/user-attachments/assets/0235e893-af96-4920-8364-1e86f73b3e6c
---
## Youtube Video Explanation
For a full walkthrough on using the Needle MCP Server with Claude and Claudie Desktop, watch this [YouTube explanation video](https://youtu.be/nVrRYp9NZYg).
---
## Installation
1. Clone the repository:
```bash
git clone https://github.com/yourusername/needle-mcp.git
```
2. Install UV globally using Homebrew in Terminal:
```bash
brew install uv
```
3. Create claude_desktop_config.json:
- For MacOS: Open directory `~/Library/Application Support/Claude/` and create the file inside it
- For Windows: Open directory `%APPDATA%/Claude/` and create the file inside it
4. Add this configuration to claude_desktop_config.json:
```json
{
"mcpServers": {
"needle_mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/needle-mcp",
"run",
"needle-mcp"
],
"env": {
"NEEDLE_API_KEY": "your_needle_api_key"
}
}
}
}
```
5. Get your Needle API key from needle.xyz
6. Update the config file:
- Replace `/path/to/needle-mcp` with your actual repository path
- Add your Needle API key
7. Quit Claude completely and reopen it
## Usage Examples
* "Create a new collection called 'Technical Docs'"
* "Add this document to the collection, which is https://needle-ai.com"
* "Search the collection for information about AI"
* "List all my collections"
## Troubleshooting
If not working:
- Make sure UV is installed globally (if not, uninstall with `pip uninstall uv` and reinstall with `brew install uv`)
- Or find UV path with `which uv` and replace `"command": "uv"` with the full path
- Verify your Needle API key is correct
- Check if the needle-mcp path in config matches your actual repository location
### Reset Claude Desktop Configuration
If you're seeing old configurations or the integration isn't working:
1. Find all Claude Desktop config files:
```bash
find / -name "claude_desktop_config.json" 2>/dev/null
```
2. Remove all Claude Desktop data:
- On MacOS: `rm -rf ~/Library/Application\ Support/Claude/*`
- On Windows: Delete contents of `%APPDATA%/Claude/`
3. Create a fresh config with only 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
```
4. Completely quit Claude Desktop (Command+Q on Mac) and relaunch it
5. If you still see old configurations:
- Check for additional config files in other locations
- Try clearing browser cache if using web version
- Verify the config file is being read from the correct location
Connection Info
You Might Also Like
MarkItDown MCP
MarkItDown-MCP is a lightweight server for converting various URIs to Markdown.
Github
The GitHub MCP Server connects AI tools to manage repositories, automate...
apisix
Apache APISIX is an API gateway that supports AI integration.
opik
Opik is a versatile tool for managing and optimizing machine learning experiments.
MCP Toolbox for Databases
MCP Toolbox for Databases is an open-source server simplifying database tool...
sqlglot
SQLGlot is a no-dependency SQL parser and transpiler supporting 31 dialects.