Build Agents with Needle MCP Server

Needle MCP Server でエージェントを構築する

Needle を通じてドキュメントを管理し、検索を実行するための MCP（Model Context Protocol）サーバーです。Claude のデスクトップアプリケーションから利用できます。

目次

• 概要
• 機能
• 使い方
  • Claude Desktop のコマンド
  • Needle での結果
• インストール
• 動画での解説

---

概要

Needle MCP Server では、次のことができます。

• ドキュメントを整理して保存し、すばやく取得できます。
• Claude の大規模言語モデルを使って、高度な検索を実行できます。
• Needle エコシステムとシームレスに連携し、高度なドキュメント管理を実現できます。

MCP（Model Context Protocol）は、LLM が外部データソースに接続する方法を標準化します。Needle MCP Server を使用すると、AI アプリケーションでセマンティック検索ツールを簡単に利用できるようになり、PDF、DOCX、XLSX などのファイルに埋もれたデータを LLM からすぐに利用できます。

最適な使用体験のため、リモート MCP サーバーの使用をおすすめします。ローカルでのセットアップは不要です。

---

機能

• ドキュメント管理： サーバーにドキュメントを簡単に追加し、整理できます。
• 検索と取得： Claude を利用した自然言語検索で、すばやく回答を得られます。
• 簡単な連携： Claude Desktop および Needle コレクションで利用できます。

---

使い方

Claude Desktop のコマンド

以下は、Claude Desktop でコマンドを使ってサーバーとやり取りする例です。

1. Claude Desktop を開き、Needle MCP Server に接続します。
2. 簡単なテキストコマンドを使用して、ドキュメントを検索、取得、または変更します。
3. Claude が返した検索結果を、使いやすいインターフェースで確認します。

Needle での結果

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

---

YouTube 動画での解説

Needle MCP Server を Claude および Claude Desktop で使用する方法の詳細については、こちらのYouTube 解説動画をご覧ください。

---

インストール

1. リモート MCP サーバー（推奨）

Claude Desktop の設定

設定ファイルを新規作成するか、既存のファイルを更新します。

• MacOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows の場合：%APPDATA%/Claude/claude_desktop_config.json

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

Cursor の設定

.cursor/mcp.json を新規作成するか、既存のファイルを更新します。

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

API キーは Needle Settings から取得してください。

次の 2 つのエンドポイントを提供しています。

• Streamable HTTP： https://mcp.needle.app/mcp（推奨）
• SSE： https://mcp.needle.app/sse

注：最新の仕様では MCP の SSE エンドポイントは非推奨となっているため、新しいクライアントでは Streamable HTTP エンドポイントを優先してください。

2. ローカルインストール

1. リポジトリをクローンします。

git clone https://github.com/needle-ai/needle-mcp.git

2. Homebrew を使用して UV をグローバルにインストールします。

brew install uv

3. 設定ファイルを作成します。
   • MacOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows の場合：%APPDATA%/Claude/claude_desktop_config.json

Claude Desktop の設定

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

Cursor の設定

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

4. /path/to/needle-mcp を実際のリポジトリのパスに置き換えます。
5. Needle API キーを追加します。
6. Claude Desktop を再起動します。

Smithery 経由でのインストール

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

3. Docker インストール

1. クローンしてビルドします。

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

2. Claude Desktop の設定（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "needle": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "needle-mcp"],
      "env": {
        "NEEDLE_API_KEY": "<your-needle-api-key>"
      }
    }
  }
}

3. Claude Desktop を再起動します

使用例

• 「Technical Docs」という新しいコレクションを作成する
• このドキュメントをコレクションに追加する。URL は https://needle.app です
• コレクション内で AI に関する情報を検索する
• すべてのコレクションを一覧表示する

トラブルシューティング

動作しない場合：

• uv がグローバルにインストールされていることを確認してください（インストールされていない場合は、pip uninstall uv でアンインストールし、brew install uv で再インストールしてください）
• または、which uv で uv のパスを確認し、"command": "uv" をフルパスに置き換えてください
• Needle API キーが正しいことを確認してください
• 設定内の needle-mcp のパスが、実際のリポジトリの場所と一致していることを確認してください

Claude Desktop の設定をリセットする

古い設定が表示される場合や、連携が機能しない場合：

1. Claude Desktop の設定ファイルをすべて探します：

find / -name "claude_desktop_config.json" 2>/dev/null

2. Claude Desktop のデータをすべて削除します：

• MacOS の場合：rm -rf ~/Library/Application\ Support/Claude/*
• Windows の場合：%APPDATA%/Claude/ の内容を削除します

3. Needle のみを含む新しい設定を作成します：

mkdir -p ~/Library/Application\ Support/Claude
cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json
<< 'EOL'
{
  "mcpServers": {
    "needle": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/needle-mcp",
        "run",
        "needle-mcp"
      ],
      "env": {
        "NEEDLE_API_KEY": "your_needle_api_key"
      }
    }
  }
}
EOL

4. Claude Desktop を完全に終了し（Mac では Command+Q）、再起動します

5. それでも古い設定が表示される場合：

• 別の場所に追加の設定ファイルがないか確認します
• ウェブ版を使用している場合は、ブラウザーのキャッシュをクリアしてみてください
• 設定ファイルが正しい場所から読み込まれていることを確認してください