Tavily Web Search MCP Server

Tavily 공식 Python SDK를 기반으로 개발된 웹 검색 MCP 서비스로, 표준 MCP Python SDK를 사용하여 구현되었으며, Streamable HTTP 전송 프로토콜을 채택하고 FastAPI + uvicorn을 통해 외부에 서비스를 제공합니다.

기능

서비스는 Tavily 공식 SDK의 주요 기능을 포괄하는 8개의 MCP 도구를 제공합니다:

deep_research_start / deep_research_result에 해당하는 연구 작업은 Tavily 서버 측에서 비동기적으로 실행되며 수 분이 소요될 수 있습니다. 먼저 deep_research_start를 호출하여 request_id를 받은 다음, deep_research_result로 status가 completed(또는 failed)가 될 때까지 폴링하세요.

Related MCP server: tavily-pool-mcp

디렉터리 구조

tavily-mcp-server/
├── app/
│   ├── config.py       # 环境变量配置加载（.env）
│   ├── tavily_tools.py # TavilyToolkit：封装 web_search / web_fetch
│   ├── server.py        # FastMCP 实例与工具注册
│   └── main.py          # FastAPI 应用 + uvicorn 入口，挂载 Streamable HTTP
├── client/
│   └── test_client.py   # 本地测试客户端（连接 MCP 服务并调用工具）
├── deploy/
│   ├── deploy.sh                # 一键同步 + 部署到远程服务器
│   └── tavily-mcp.service       # systemd 服务单元
├── requirements.txt
├── .env.example
└── .gitignore

환경 요구사항

• Python 3.12(로컬은 conda 환경 llm_factory_envs에서 개발, 원격 서버는 llm_env 사용)

• Tavily API Key(app.tavily.com에서 신청)

로컬 개발 및 테스트

1. 환경 변수 준비

cp .env.example .env
# 编辑 .env，填入 TAVILY_API_KEY；本地测试保持 MCP_HOST=127.0.0.1

2. 의존성 설치 (conda 환경 llm_factory_envs)

conda activate llm_factory_envs
pip install -r requirements.txt

3. MCP 서비스 시작

python -m app.main
# 服务启动后监听 http://127.0.0.1:20260/mcp
# 健康检查: curl http://127.0.0.1:20260/health

4. 테스트 클라이언트로 검증

새 터미널을 엽니다:

conda activate llm_factory_envs
python -m client.test_client --url http://127.0.0.1:20260/mcp

테스트 클라이언트는 순서대로: 서비스 연결 → 사용 가능한 도구 나열 → web_search / web_fetch / web_crawl / web_map / qna_search / search_context 호출 → 결과 출력을 수행합니다.

심층 연구 작업은 시간이 오래 걸릴 수 있으며(수 분 소요 가능), 기본적으로 테스트되지 않습니다. deep_research_start / deep_research_result도 함께 검증하려면:

python -m client.test_client --url http://127.0.0.1:20260/mcp --deep-research
# 也可自定义研究任务描述:
python -m client.test_client --url http://127.0.0.1:20260/mcp --deep-research "近期国产大模型有哪些重要发布"

이 모드는 작업 제출 후 10초마다 deep_research_result를 폴링하여 상태가 completed / failed가 될 때까지 대기합니다.

원격 서버 배포

원격 서버 정보: 101.47.67.15, SSH(비밀번호 없는 로그인 설정 완료)를 통해 배포하며, 원격 conda 환경 llm_env를 사용하고, 서비스 포트는 20260으로 고정됩니다.

1. 원격 .env 구성

로컬 .env에서 MCP_HOST를 0.0.0.0(공용 네트워크 수신)으로 변경하고 MCP_PORT는 20260으로 유지한 후, 배포 스크립트를 실행하면 자동으로 scp를 통해 .env가 동기화됩니다(원격과 로컬에서 다른 키를 사용해야 하는 경우 원격에서 직접 /opt/tavily-mcp-server/.env를 수동으로 관리할 수 있습니다).

2. 원클릭 배포

bash deploy/deploy.sh

이 스크립트는 다음 작업을 수행합니다:

1. 프로젝트 파일을 root@101.47.67.15:/opt/tavily-mcp-server에 rsync합니다(.git, __pycache__ 등 제외)

2. 로컬에 .env가 있으면 동기화합니다

3. 원격 llm_env 환경에 의존성을 설치합니다

4. systemd 서비스를 설치/업데이트하고 재시작합니다

3. 서버 방화벽 / 보안 그룹

클라우드 서비스 제공업체 콘솔의 보안 그룹 규칙에서 TCP 20260 포트를 허용했는지 확인하세요(deploy.sh는 클라우드 보안 그룹을 자동으로 수정하지 않으므로 제공업체 콘솔에서 수동으로 열어야 합니다). 서버 자체에서 firewalld/ufw가 활성화된 경우에도 해당 포트를 허용해야 합니다. 예:

# firewalld
ssh root@101.47.67.15 "firewall-cmd --permanent --add-port=20260/tcp && firewall-cmd --reload"

3. 원격 배포 검증

curl http://101.47.67.15:20260/health
python -m client.test_client --url http://101.47.67.15:20260/mcp

일반적인 운영 명령

ssh root@101.47.67.15 "systemctl status tavily-mcp.service --no-pager"
ssh root@101.47.67.15 "journalctl -u tavily-mcp.service -f"
ssh root@101.47.67.15 "systemctl restart tavily-mcp.service"

MCP 클라이언트 구성

배포 완료 후, Streamable HTTP를 지원하는 모든 MCP 클라이언트에서 다음 구성을 통해 이 서비스에 연결할 수 있습니다:

{
  "mcpServers": {
    "tavily-web-search": {
      "type": "streamable_http",
      "url": "http://101.47.67.15:20260/mcp"
    }
  }
}

로컬 연동이 필요하면 URL을 http://127.0.0.1:20260/mcp로 교체하면 됩니다.

환경 변수 설명

보안 안내

• .env 파일은 .gitignore에 포함되어 있으며 GitHub 저장소에 커밋하지 마십시오.

• 코드에 키를 하드코딩하지 마십시오. 모든 민감한 정보는 환경 변수를 통해 주입됩니다(python-dotenv로 로드).