# Tavily Search MCP Server 🔍

> **让你的 AI Agent 拥有实时的网络搜索能力！**

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的服务器，为 Claude Desktop、Cursor、Hermes Agent 等支持 MCP 的 AI 客户端提供**实时网络搜索**和**网页内容提取**能力。

## ✨ 功能

| 工具 | 描述 |
|------|------|
| **`web_search_tool`** | 搜索互联网获取实时信息。支持通用搜索、新闻搜索、金融数据。返回带标题、URL 和摘要的格式化结果。 |
| **`extract_content_tool`** | 从一个或多个 URL 提取干净、LLM 可读的网页内容。完美适用于阅读文章、文档等。 |

## 🚀 快速开始

### 1. 安装

```bash
pip install mcp-tavily-search
```

或者从源码安装：

```bash
git clone https://github.com/lingxi-dev/mcp-tavily-search.git
cd mcp-tavily-search
pip install -e .
```

### 2. 设置 API Key

```bash
# Linux / macOS
export TAVILY_API_KEY="tavily-xxxxxxxxxxxxxxxx"

# Windows (cmd)
set TAVILY_API_KEY=tavily-xxxxxxxxxxxxxxxx

# Windows (PowerShell)
$env:TAVILY_API_KEY="tavily-xxxxxxxxxxxxxxxx"
```

也可以在项目目录创建 `.env` 文件：

```env
TAVILY_API_KEY=tavily-xxxxxxxxxxxxxxxx
```

获取 API Key：[app.tavily.com](https://app.tavily.com)

### 3. 启动服务器

```bash
# stdio 模式（默认，适用于 Claude Desktop 等本地客户端）
mcp-tavily-search

# SSE 模式（适用于远程/网络连接）
mcp-tavily-search --transport sse --host 0.0.0.0 --port 8000
```

### 4. 配置 Claude Desktop

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "tavily-search": {
      "command": "mcp-tavily-search",
      "env": {
        "TAVILY_API_KEY": "tavily-xxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### 5. 配置 Hermes Agent

在 `~/.hermes/config.yaml` 中添加：

```yaml
mcp_servers:
  tavily-search:
    command: mcp-tavily-search
    env:
      TAVILY_API_KEY: tavily-xxxxxxxxxxxxxxxx
```

## ⚙️ 高级用法

### 搜索参数

```python
# 搜索工具支持以下参数：
web_search_tool(
    query="2026年 AI Agent 发展趋势",
    max_results=10,        # 结果数量 (1-20)
    search_depth="advanced",  # "basic" 快速 / "advanced" 高质量
    include_answer=True,    # 是否包含 AI 摘要
    topic="news",          # "general" / "news" / "finance"
    days=30                # 回溯天数
)
```

### 提取内容

```python
extract_content_tool(
    urls=[
        "https://example.com/article1",
        "https://example.com/article2"
    ]
)
```

## 🏗️ 项目结构

```
mcp-tavily-search/
├── pyproject.toml          # 项目配置 & 依赖
├── README.md               # 本文档
├── LICENSE                 # MIT 许可证
├── .env.example            # 环境变量模板
└── src/
    └── mcp_tavily_search/
        ├── __init__.py
        ├── server.py       # FastMCP 服务器入口
        └── tools/
            ├── __init__.py
            ├── search.py   # Tavily 搜索 API 封装
            └── content.py  # Tavily 内容提取 API 封装
```

## 🔧 技术栈

- **[FastMCP](https://github.com/PrefectHQ/fastmcp)** — MCP 服务器框架（官方推荐，70% MCP 服务器使用）
- **[Tavily API](https://app.tavily.com)** — 为 AI Agent 优化的搜索引擎
- **[httpx](https://www.python-httpx.org/)** — 异步 HTTP 客户端

## 📦 发布到 PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## 📄 许可证

MIT