Ai Research Agent MCP

🚀 MCP搭載のAI研究エンジニア

単一のプロンプトから、完全な調査レポート（ウェブ + あなたのメモ + コード + チャート）を生成します。

このシステムは、Model Context Protocol (MCP) を使用して、調査、コーディング、包括的なレポートの作成を自動的に行うAIエージェントです。

🚀 クイックスタート

前提条件

• Python 3.10以上（Python 3.11以上が推奨）
• Claude Desktop または Cursor IDE（MCP互換クライアント）
• Git（リポジトリのクローン用）
• uv（オプションだが推奨 - ここからインストール）または pip
• （オプション）拡張機能のためのAPIキー

インストール手順

1. リポジトリのクローン

git clone https://github.com/prabureddy/ai-research-agent-mcp.git
cd ai-research-agent-mcp

2. 依存関係のインストール

オプションA: uvを使用する（推奨 - 10〜100倍高速！）

# サーバーディレクトリに移動
cd server

# まだuvをインストールしていない場合はインストールする
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 仮想環境を作成してアクティブ化する
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 必要なパッケージをインストールする（pipよりもはるかに高速！）
uv pip install -r requirements.txt

オプションB: pipを使用する（従来の方法）

# サーバーディレクトリに移動
cd server

# 仮想環境を作成してアクティブ化する
python3.11 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 必要なパッケージをインストールする
pip install -r requirements.txt

3. 環境の設定

# プロジェクトのルートに戻る
cd ..

# 環境ファイルのサンプルをコピーする
cp .env.example .env

# 好みのテキストエディタで.envを編集する（オプション）
nano .env  # またはvim、codeなど

環境設定（オプション）:

# オプション: Brave Searchを使用する場合（DuckDuckGoより良い）
BRAVE_API_KEY=your_brave_api_key_here

# オプション: 将来的なAnthropic統合のため
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# オプション: パスをカスタマイズする
RESEARCH_RUNS_DIR=./research_runs
KNOWLEDGE_BASE_DIR=./knowledge_base

# RAGはデフォルトでローカル埋め込みを使用する（APIキー不要！）
USE_LOCAL_EMBEDDINGS=true
EMBEDDING_MODEL=all-MiniLM-L6-v2

⚠️ 重要: .env ファイルをバージョン管理にコミットしないでください。すでに .gitignore に含まれています。

注意: システムはデフォルトでローカルのsentence-transformers埋め込みを使用するため、RAG機能にはAPIキーは必要ありません！

4. 必要なディレクトリの作成

# データストレージ用のディレクトリを作成する
mkdir -p research_runs knowledge_base data/vector_db logs

5. Claude Desktopの設定

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json を編集する Windows: %APPDATA%\Claude\claude_desktop_config.json を編集する Linux: ~/.config/Claude/claude_desktop_config.json を編集する

まずは絶対パスを見つける:

# プロジェクトディレクトリで実行する
pwd
# 出力例: /Users/yourname/Projects/ai-research-agent-mcp

# Pythonのパスを見つける（仮想環境を使用している場合）
which python  # または: which python3.11
# 出力例: /Users/yourname/Projects/ai-research-agent-mcp/server/venv/bin/python3.11

設定テンプレート:

以下の設定を追加し、パスと環境変数を実際の値に置き換えてください。

{
  "mcpServers": {
    "research-engineer": {
      "command": "/absolute/path/to/python",
      "args": [
        "/absolute/path/to/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key_here_or_remove_this_line",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key_here_or_remove_this_line",
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "USE_LOCAL_EMBEDDINGS": "true",
        "VECTOR_DB_PATH": "/absolute/path/to/ai-research-agent-mcp/data/vector_db",
        "CHUNK_SIZE": "1000",
        "CHUNK_OVERLAP": "200",
        "SANDBOX_TIMEOUT": "30",
        "SANDBOX_MAX_MEMORY_MB": "512",
        "ALLOWED_PACKAGES": "numpy,pandas,matplotlib,seaborn,scipy,scikit-learn",
        "RESEARCH_RUNS_DIR": "/absolute/path/to/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/absolute/path/to/ai-research-agent-mcp/knowledge_base",
        "LOG_LEVEL": "INFO",
        "LOG_FILE": "/absolute/path/to/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

⚠️ 重要な注意事項:

• すべてのファイルパスには 絶対パス を使用してください（~ や相対パスは使用しないでください）
• 仮想環境を使用している場合は、仮想環境内のPythonパスを使用してください
• 持っていないAPIキーは削除するか空にしてください（DuckDuckGoはキーなしで動作します）
• env 内のすべてのパスは絶対パスである必要があります

macOS/Linuxの例（仮想環境を使用する場合）:

{
  "mcpServers": {
    "research-engineer": {
      "command": "/Users/yourname/Projects/ai-research-agent-mcp/server/venv/bin/python3.11",
      "args": [
        "/Users/yourname/Projects/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

macOS/Linuxの例（uvを使用する場合）:

{
  "mcpServers": {
    "research-engineer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/yourname/Projects/ai-research-agent-mcp/server",
        "python",
        "src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

Windowsの例:

{
  "mcpServers": {
    "research-engineer": {
      "command": "C:/Users/yourname/Projects/ai-research-agent-mcp/server/venv/Scripts/python.exe",
      "args": [
        "C:/Users/yourname/Projects/ai-research-agent-mcp/server/src/server.py"
      ],
      "env": {
        "SEARCH_PROVIDER": "duckduckgo",
        "MAX_SEARCH_RESULTS": "10",
        "USE_LOCAL_EMBEDDINGS": "true",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "VECTOR_DB_PATH": "C:/Users/yourname/Projects/ai-research-agent-mcp/data/vector_db",
        "RESEARCH_RUNS_DIR": "C:/Users/yourname/Projects/ai-research-agent-mcp/research_runs",
        "KNOWLEDGE_BASE_DIR": "C:/Users/yourname/Projects/ai-research-agent-mcp/knowledge_base",
        "LOG_FILE": "C:/Users/yourname/Projects/ai-research-agent-mcp/logs/research_engineer.log"
      }
    }
  }
}

6. Claude Desktopの再起動

変更を反映するために、Claude Desktopを完全に終了して再起動してください。

インストールの確認

Claude Desktopで以下を入力します。

List available tools

web_search、web_research、execute_code、create_research_run などが表示されるはずです。

最初の調査タスク

次の簡単なタスクを試してみてください。

Research the current state of electric vehicles in 2026. 
Include market size, major players, and growth trends. 
Create a simple visualization showing EV adoption over time.

エージェントは以下のことを行います。

1. ウェブ上でEVのデータを検索する
2. チャートを作成するPythonコードを書く
3. 出所付きで調査結果を提示する

✨ 主な機能

• ✅ 自律的な多段階調査
• ✅ ウェブ検索とコンテンツ抽出
• ✅ 個人の知識ベースに対するRAG
• ✅ 出力をキャプチャした安全なコード実行
• ✅ 構造化されたレポート生成
• ✅ 自己評価と品質指標
• ✅ 包括的なロギングとトレーシング
• ✅ 再現可能な調査実行

📦 インストール

⚡ ワンライナーでのインストール

オプション1: uvを使用する（推奨 - 高速！）

git clone https://github.com/prabureddy/ai-research-agent-mcp.git \
  && cd ai-research-agent-mcp/server \
  && uv venv \
  && source .venv/bin/activate \
  && uv pip install -r requirements.txt

オプション2: pipを使用する（従来の方法）

git clone https://github.com/prabureddy/ai-research-agent-mcp.git \
  && cd ai-research-agent-mcp/server \
  && python3 -m venv venv \
  && source venv/bin/activate \
  && pip3 install -r requirements.txt

⚡ クイックスタート: クローン → インストール → Claude Desktopを設定 → 5分で調査を開始！

💻 使用例

基本的な使用法

Research the pros and cons of electric scooters vs bikes for urban commuting.

エージェントは以下のことを行います。

1. ウェブ上で関連情報を検索する
2. 調査結果を整理する
3. 要約を提示する

高度な使用法

Deep dive: Compare electric scooters vs bikes for my 5-mile daily commute. 
Build a cost calculator in Python that shows total cost of ownership over 3 years.
Include purchase price, maintenance, electricity/none, and create visualizations.

エージェントは以下のことを行います。

1. コスト、メンテナンス、使用データを調査する
2. Pythonのコスト計算機を構築する
3. 比較チャートを作成する
4. 包括的なレポートを書く
5. すべてを調査実行ディレクトリに保存する
6. 作業を自己評価する

📚 ドキュメント

ツールの使用例

ウェブ調査

検索のみ:

Use web_search to find the latest news about AI regulation in 2026

スクレイピングを含む包括的な調査:

Use web_research to gather detailed information about multifamily real estate cap rates, 
and scrape the top 5 results for full content

特定のURLをスクレイピング:

Scrape this article and summarize the key points: https://example.com/article

知識ベース（RAG）

メモをインデックス化する:

Index all files in my knowledge_base directory so I can query them later

知識ベースをクエリする:

Query my knowledge base for information about real estate investment strategies

ウェブと知識ベースを組み合わせる:

Research current EV market trends using both web search and my personal notes 
in the knowledge base

コード実行

単純な計算:

Write Python code to calculate the compound annual growth rate (CAGR) 
for an investment that grew from $10,000 to $25,000 over 5 years

データ分析:

Create a Python script that:
1. Generates sample sales data for 12 months
2. Calculates moving averages
3. Creates a line chart with trend line
4. Prints summary statistics

財務モデリング:

Build a mortgage calculator in Python that:
- Takes loan amount, interest rate, and term
- Calculates monthly payment
- Shows amortization schedule
- Creates a chart showing principal vs interest over time

ベストプラクティス

1. 具体的にする

❌ 曖昧なプロンプト:

Research AI

✅ 具体的なプロンプト:

Research the current state of large language models in 2026, focusing on:
- Model sizes and capabilities
- Training costs
- Commercial applications
- Regulatory challenges

2. 構造を要求する

❌ 構造がないプロンプト:

Tell me about real estate

✅ 構造があるプロンプト:

Research multifamily real estate investment in 2026:
1. Current market conditions
2. Financial modeling
3. Risk analysis
4. Recommendations

3. ツールを組み合わせる

✅ 効果的なプロンプト:

Research electric vehicle adoption rates using:
1. Web search for latest statistics
2. My knowledge base for past analysis
3. Python code to project future adoption
4. Visualizations of trends

4. 評価を要求する

✅ 品質に焦点を当てたプロンプト:

After completing the analysis, evaluate your work and tell me:
- What data sources were most valuable?
- What are the limitations of this analysis?
- What would make this analysis more robust?

🔧 技術詳細

システムの概要

┌─────────────────────────────────────────────────────────────┐
│                    Claude Desktop / Cursor                   │
│                     (MCP Client/Host)                        │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                    MCP Server (Python)                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Tool Registry & Router                   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Web Research │  │   RAG Tool   │  │Code Sandbox  │     │
│  │              │  │              │  │              │     │
│  │ • Search     │  │ • Embeddings │  │ • Restricted │     │
│  │ • Scrape     │  │ • ChromaDB   │  │   Python     │     │
│  │ • Extract    │  │ • Query      │  │ • Safe Exec  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │  Workspace   │  │  Evaluator   │                        │
│  │              │  │              │                        │
│  │ • File I/O   │  │ • Metrics    │                        │
│  │ • Organize   │  │ • Critique   │                        │
│  │ • Manage     │  │ • Quality    │                        │
│  └──────────────┘  └──────────────┘                        │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
        ┌────────────────────────────────────┐
        │      External Services              │
        │                                     │
        │  • DuckDuckGo / Brave Search       │
        │  • OpenAI Embeddings API           │
        │  • Web Scraping (HTTP)             │
        └────────────────────────────────────┘
                         │
                         ▼
        ┌────────────────────────────────────┐
        │      Local Storage                  │
        │                                     │
        │  • research_runs/                  │
        │  • knowledge_base/                 │
        │  • data/vector_db/                 │
        │  • logs/                           │
        └────────────────────────────────────┘

コアコンポーネント

1. MCPサーバー ()

責任:

• MCPプロトコルを介してツールを公開する
• ツール呼び出しを適切なハンドラーにルーティングする
• エラーとロギングを処理する
• サーバーのライフサイクルを管理する

技術:

• Python 3.10以上
• MCP SDK (mcp パッケージ)
• I/O操作に非同期/待機を使用する

2. ウェブ調査ツール ()

責任:

• ウェブ上で情報を検索する
• コンテンツをスクレイピングしてクリーンな内容を抽出する
• レート制限とリトライを処理する

コンポーネント:

• 検索プロバイダー: DuckDuckGo（デフォルト、APIキー不要）、Brave Search（オプション）
• コンテンツ抽出: メインコンテンツにTrafilatura、メタデータにBeautifulSoupを使用する

3. RAGツール ()

責任:

• ドキュメントをベクトルデータベースにインデックス化する
• 知識ベースに対するセマンティック検索を行う
• 複数のファイル形式（Markdown、PDF、DOCX）をサポートする

コンポーネント:

• ベクトルデータベース: ChromaDB（永続的、ローカル）
• 埋め込み: OpenAI text-embedding-3-small
• チャンク化戦略: 1000文字で200文字のオーバーラップ

4. コードサンドボックス ()

責任:

• Pythonコードを安全に実行する
• 出力とプロットをキャプチャする
• リソース制限を適用する

セキュリティレイヤー:

1. RestrictedPython: ASTレベルのコード制限
2. リソース制限: メモリとCPUの制約
3. タイムアウト: 実行時間制限
4. 許可されたパッケージ: 安全なライブラリのホワイトリスト（numpy、pandas、matplotlibなど）

5. ワークスペースツール ()

責任:

• 調査出力を整理する
• ファイルの入出力を管理する
• 調査実行を追跡する

ディレクトリ構造:

research_runs/
└── YYYY-MM-DD_HHMMSS_task-name/
    ├── metadata.json
    ├── report.md
    ├── evaluation.json
    ├── sources.json
    ├── code/
    │   └── *.py
    ├── charts/
    │   └── *.png
    └── data/
        └── *.json

6. 評価ツール ()

責任:

• 品質評価
• 自己批判の生成
• 指標のトラッキング

品質指標（0〜10のスケール）:

• 明瞭さ、データの根拠、完全性、コード品質、実行可能性、信頼度

📄 ライセンス

MITライセンスの下で公開されています。

AI研究エンジニアを楽しんでください！ 🚀