shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

ai-research-agent-mcp

一个基于MCP协议的自主AI研究代理，能够通过单次提示完成网络搜索、知识库检索、代码编写、图表生成和报告撰写等完整研究流程。

article

README

🚀 MCP 驱动的 AI 研究工程师

这是一个基于模型上下文协议（MCP）的自主 AI 代理，它能够将单个提示转化为完整的研究报告，整合网络信息、个人笔记、代码和图表等内容，为研究工作提供全面且高效的支持。

License: MIT Python 3.10+ MCP
PRs Welcome YouTube
GitHub stars

🚀 快速开始

前提条件

  • 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. 在网络上搜索电动汽车数据
  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

💻 使用示例

基础用法

简单查询

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 服务器 (server/src/server.py)

职责：

  • 通过 MCP 协议暴露工具
  • 将工具调用路由到适当的处理程序
  • 处理错误和日志记录
  • 管理服务器生命周期

技术：

  • Python 3.10+
  • MCP SDK (mcp 包)
  • 用于 I/O 操作的异步/等待
2. 网络研究工具 (server/src/tools/web_research.py)

职责：

  • 在网络上搜索信息
  • 抓取并提取干净的内容
  • 处理速率限制和重试

组件：

  • 搜索提供商： DuckDuckGo（默认，无需 API 密钥），Brave Search（可选）
  • 内容提取： Trafilatura 用于提取主要内容，BeautifulSoup 用于提取元数据
3. RAG 工具 (server/src/tools/rag_tool.py)

职责：

  • 将文档索引到向量数据库中
  • 对知识库进行语义搜索
  • 支持多种文件格式（Markdown、PDF、DOCX）

组件：

  • 向量数据库： ChromaDB（持久化，本地）
  • 嵌入： OpenAI text-embedding-3-small
  • 分块策略：1000 字符，重叠 200 字符
4. 代码沙箱 (server/src/tools/code_sandbox.py)

职责：

  • 安全地执行 Python 代码
  • 捕获输出和绘图
  • 实施资源限制

安全层：

  1. RestrictedPython：AST 级别的代码限制
  2. 资源限制：内存和 CPU 约束
  3. 超时：执行时间限制
  4. 允许的包：安全库的白名单（numpy、pandas、matplotlib 等）
5. 工作区工具 (server/src/tools/workspace.py)

职责：

  • 组织研究输出
  • 管理文件 I/O
  • 跟踪研究运行

目录结构：

research_runs/
└── YYYY-MM-DD_HHMMSS_task-name/
    ├── metadata.json
    ├── report.md
    ├── evaluation.json
    ├── sources.json
    ├── code/
    │   └── *.py
    ├── charts/
    │   └── *.png
    └── data/
        └── *.json
6. 评估工具 (server/src/tools/evaluator.py)

职责：

  • 质量评估
  • 自我批判生成
  • 指标跟踪

质量指标（0 - 10 分制）：

  • 清晰度、数据依据、完整性、代码质量、可操作性、置信度

配置

环境变量

查看 .env.example 以获取所有可用的配置选项：

# 搜索配置
BRAVE_API_KEY=...           # 可选：比 DuckDuckGo 更好的搜索
SEARCH_PROVIDER=duckduckgo  # duckduckgo 或 brave
MAX_SEARCH_RESULTS=10

# RAG 配置（默认使用本地嵌入）
USE_LOCAL_EMBEDDINGS=true
EMBEDDING_MODEL=all-MiniLM-L6-v2
VECTOR_DB_PATH=./data/vector_db
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# 代码沙箱配置
SANDBOX_TIMEOUT=30
SANDBOX_MAX_MEMORY_MB=512

# 目录配置
RESEARCH_RUNS_DIR=./research_runs
KNOWLEDGE_BASE_DIR=./knowledge_base

# 日志记录
LOG_LEVEL=INFO

Cursor IDE 配置（替代方案）

1. 打开 Cursor 设置

按下 Cmd+,（Mac）或 Ctrl+,（Windows/Linux）

2. 搜索 "MCP"

找到 MCP 服务器配置部分。

3. 添加服务器配置

添加与 Claude Desktop 相同的配置（详见上面的第 5 节示例）。

基本示例：

{
  "research-engineer": {
    "command": "/absolute/path/to/python",
    "args": [
      "/absolute/path/to/ai-research-agent-mcp/server/src/server.py"
    ],
    "env": {
      "SEARCH_PROVIDER": "duckduckgo",
      "USE_LOCAL_EMBEDDINGS": "true",
      "VECTOR_DB_PATH": "/absolute/path/to/data/vector_db",
      "RESEARCH_RUNS_DIR": "/absolute/path/to/research_runs",
      "KNOWLEDGE_BASE_DIR": "/absolute/path/to/knowledge_base"
    }
  }
}

使用 uv：

{
  "research-engineer": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/absolute/path/to/ai-research-agent-mcp/server",
      "python",
      "src/server.py"
    ],
    "env": {
      "SEARCH_PROVIDER": "duckduckgo",
      "USE_LOCAL_EMBEDDINGS": "true"
    }
  }
}

项目结构

完整的文件和目录结构：

ai-research-agent-mcp/
│
├── README.md                          # 本文件 - 完整文档
├── LICENSE                            # MIT 许可证
├── .gitignore                         # Git 忽略规则
├── .env.example                       # 示例环境变量
│
├── server/                            # MCP 服务器实现
│   ├── requirements.txt               # Python 依赖项
│   ├── pyproject.toml                 # 项目元数据和构建配置
│   │
│   └── src/                           # 源代码
│       ├── __init__.py                # 包初始化
│       ├── server.py                  # 主 MCP 服务器入口点
│       ├── config.py                  # 配置管理
│       │
│       └── tools/                     # 工具实现
│           ├── __init__.py            # 工具包初始化
│           ├── web_research.py        # 网络搜索和抓取
│           ├── rag_tool.py            # 用于知识库的向量 RAG
│           ├── code_sandbox.py        # 安全的 Python 代码执行
│           ├── workspace.py           # 文件和工作区管理
│           └── evaluator.py           # 质量评估和批判
│
├── agent/                             # 代理编排
│   └── prompts/                       # 系统提示和模板
│       └── research_agent.md          # 主要研究代理提示
│
├── config/                            # 配置文件
│   └── claude_desktop_config.json     # 示例 Claude Desktop 配置
│
├── examples/                          # 示例任务和输出
│   └── example_research_task.md       # 带有预期输出的详细示例
│
├── knowledge_base/                    # 个人知识库（用户内容）
│   └── example_notes.md               # RAG 示例笔记
│
├── research_runs/                     # 研究输出目录（运行时创建）
│   └── YYYY-MM-DD_HHMMSS_task-name/   # 单个研究运行
│       ├── metadata.json              # 运行元数据
│       ├── report.md                  # 最终报告
│       ├── evaluation.json            # 自我评估
│       ├── sources.json               # 数据源
│       ├── code/                      # 生成的代码
│       │   └── *.py
│       ├── charts/                    # 可视化
│       │   └── *.png
│       └── data/                      # 数据文件
│           └── *.json
│
├── data/                              # 数据存储（运行时创建）
│   └── vector_db/                     # ChromaDB 向量数据库
│
└── logs/                              # 日志文件（运行时创建）
    └── research_engineer.log          # 应用程序日志

关键文件说明

| 文件 | 用途 | |------|---------| | server/src/server.py | 带有工具注册表的主 MCP 服务器 | | server/src/config.py | 配置加载和验证 | | server/src/tools/web_research.py | 网络搜索和抓取 | | server/src/tools/rag_tool.py | 向量数据库和语义搜索 | | server/src/tools/code_sandbox.py | 安全的 Python 代码执行 | | server/src/tools/workspace.py | 文件 I/O 和研究运行管理 | | server/src/tools/evaluator.py | 质量指标和自我批判 |

🔧 技术细节

系统架构设计

本系统采用模块化设计，通过 MCP 协议实现组件间的通信。MCP 服务器作为核心，负责工具的注册、路由和管理。各个工具模块（如网络研究、RAG、代码沙箱等）独立实现特定功能，通过 MCP 服务器进行调用。这种设计使得系统具有良好的可扩展性和维护性。

安全机制

代码沙箱采用多层安全机制确保代码执行的安全性。RestrictedPython 对代码进行 AST 级别的限制，防止恶意代码的执行。同时，设置了内存和 CPU 约束、执行时间限制以及允许的包白名单，进一步保障系统的安全稳定运行。

数据处理与存储

RAG 工具使用 ChromaDB 作为向量数据库，将文档进行嵌入并存储。通过分块策略，将文档分割成合适大小的块，提高检索效率。研究输出和日志数据分别存储在 research_runs 和 logs 目录中，便于管理和追溯。

📄 许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

希望你享受使用本 AI 研究工程师！🚀

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client