Tavily MCP 키 풀

简体中文版 README: README.zh.md

왜? 여러 개의 Tavily API 키(여러 계정, 팀 예산, 일괄 구매 크레딧 등)를 보유하고 있고 이를 AI 코딩 에이전트를 통해 사용한다면, 세 가지 문제에 빠르게 직면하게 됩니다:

1. 단일 키 병목 현상 — 하나의 키에 대한 속도 제한이 모든 것을 지연시킵니다.

2. 무음 실패 — 키가 만료되거나, 할당량에 도달하거나, 취소되면 검색이 그냥... 중단됩니다.

3. 가시성 부족 — 어떤 키가 사용되고 있는지, 얼마나 사용되었는지 알 수 없습니다.

이 프로젝트는 세 가지 문제를 모두 해결합니다: 키 풀을 라운드 로빈 방식으로 순회하고, 죽은 키를 자동 비활성화하며, 사용 통계를 노출하는 소형 MCP 서버입니다. 따라서 Claude Desktop, Cursor, DeepSeek Harness 또는 모든 MCP 클라이언트에 워크플로우 변경 없이 바로 적용할 수 있습니다.

SQLite 기반 라운드 로빈 API 키 풀, 내장 사용 추적, 자동 상태 기반 장애 조치, 독립형 FastAPI 대시보드를 갖춘 Tavily MCP 서버입니다. 표준 MCP 프로토콜 — 모든 MCP 호환 클라이언트(Claude Desktop, Cursor, DeepSeek Harness 등)와 함께 작동합니다.

주요 기능

• 🔄 N개의 Tavily API 키에 대한 라운드 로빈 키 순환 (SQLite, 시작 비용 없음).

• 📊 사용 추적: 키별 요청 수, 오류 수, 소비된 크레딧.

• 🩺 자동 상태 확인: 가벼운 검색으로 모든 키를 프로브하고, 죽은 키는 자동 비활성화하며, 결과를 tavily_pool_status를 통해 노출합니다.

• 🛠️ 6개의 핵심 MCP 도구 (Tavily와 동일: search, extract, crawl, map, research) 추가로 tavily_pool_status 및 tavily_research_status (비동기 가져오기).

• 🌐 독립형 FastAPI 대시보드 (CORS 활성화, 루프백 전용) — 통계, 키별 보기, 추가/제거/비활성화/활성화, 원클릭 상태 프로브.

• 🔌 stdio를 통한 모든 MCP 클라이언트에 바로 적용 가능; DSH 통합은 한 페이지 패치 + 예제 클라이언트 플러그인입니다 (examples/dsh-integration/ 참조).

공식 tavily-mcp와의 차이점

아키텍처

+--------------------------------------------------+
|  MCP clients (Claude Desktop / Cursor / DSH …)   |
+--------+---------------------+-------------------+
         | stdio (JSON-RPC)     | HTTPS / CORS
+--------▼--------------+     +▼-----------------------+
|  mcp_server.py (FastMCP)|     |  dashboard.py (FastAPI) |
|  + key_pool.py (SQLite) |     |  uvicorn 127.0.0.1:8000 |
+----------------------+--+     +-----+----------------+
                       |              |
                       v              v
                tavily_keys.db  <— SQLite-backed pool
                       |
                       v
              Tavily REST API (round-robin over N keys)

빠른 시작

1. 의존성 설치

python -m venv .venv
. .venv/bin/activate        # Linux/macOS
# or:  .venv\Scripts\Activate.ps1   (Windows PowerShell)
pip install -r requirements.txt

requirements.txt에 고정된 mcp 제약 조건은 **<2.0**입니다: DSH 통합 / 함정 #1 참조 — mcp 2.x에서 FastMCP 임포트 경로가 변경되었습니다.

2. API 키 추가

한 줄에 하나의 키로 keys.txt 파일을 생성합니다:

tvly-xxxxxxxxxxxxxxxx
tvly-yyyyyyyyyyyyyyyy

그런 다음 가져옵니다:

python cli.py add --from-file keys.txt

또는 대시보드(다음 단계)를 시작하고 API 키 추가 양식에 붙여넣습니다. 키는 tavily_keys.db(SQLite)에 일반 텍스트로 저장되므로 풀이 시작 비용 없이 라운드 로빈할 수 있습니다 — 보안 참조.

3. MCP 서버 시작

직접 stdio MCP 서버(모든 MCP 클라이언트)의 경우:

./run_mcp.sh                                # Linux/macOS
# or:  .venv\Scripts\python.exe mcp_server.py   (Windows)

서버는 7개의 도구를 알립니다. MCP 인식 클라이언트에서 공개 이름은 tavily_search, tavily_extract 등으로 표시됩니다.

4. 대시보드 시작 (선택 사항, 독립 프로세스)

./run_dashboard.sh                          # default port 8000
# or:  .venv\Scripts\python.exe -m uvicorn dashboard:app --host 127.0.0.1 --port 8000

브라우저에서 http://127.0.0.1:8000을 엽니다. 대시보드는 CORS가 활성화되어 루프백 출처에 대해 열려 있으므로 다른 UI의 임베디드 설정 패널에서 호출할 수 있습니다.

MCP 도구

CLI

python cli.py list                 # all keys
python cli.py list --active        # only active
python cli.py stats                # JSON dump of pool state
python cli.py health               # probe every active key; deactivate dead ones
python cli.py recent -n 20         # recent request log
python cli.py add tvly-... [...]   # add one or more keys
python cli.py add --from-file keys.txt
python cli.py activate tvly-xx****yy     # masked id, see `list`
python cli.py deactivate tvly-xx****yy --reason "manually disabled"
python cli.py remove tvly-xx****yy

Claude Desktop / Cursor / 기타 일반 MCP 클라이언트와 함께 사용

MCP stdio 명령을 허용하는 모든 클라이언트의 경우:

{
  "mcpServers": {
    "tavily": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["mcp_server.py"],
      "cwd": "/absolute/path/to/this/repo"
    }
  }
}

또는 스트리밍 가능 HTTP — 클라이언트가 지원하고 서버를 직접 HTTP 전송으로 래핑한 경우 (이 저장소의 범위를 벗어남).

DeepSeek Harness (DSH) 통합

@deepseek-ai/dsh 0.1.0-rc.6 (웹 프로필)에서 테스트됨.

DeepSeek Harness (dsh)는 Cordis 플러그인 프레임워크를 사용하며 공식 MCP 클라이언트 브리지(@deepseek-ai/dsh-mcp-client)를 제공합니다. 따라서 통합은 매우 간단합니다: 하나의 사용자 패치 레이어 + 예제 브라우저 측 플러그인(이 저장소의 examples/dsh-integration/client-tavily-panel/).

A. DSH에 Tavily MCP 서버 등록

~/.dsh/profiles/web/cordis.patch.yml (모든 번들 후 적용되는 사용자 패치 레이어)을 편집합니다. 새 insert 블록을 추가합니다 — 아래 값은 저장소가 C:\Users\ASUS\.dsh\tavily-pool\에 있다고 가정합니다:

- insert:
    - id: mcp-tavily
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: tavily
        command: 'C:\Users\ASUS\.dsh\tavily-pool\.venv\Scripts\python.exe'
        args: ['mcp_server.py']
        cwd: 'C:\Users\ASUS\.dsh\tavily-pool'
        # research can take >2 minutes on big topics; the default 30s is too tight
        toolCallTimeoutMs: 600000
        failOnStartupError: false

재시작하기 전에 dsh --profile web --dump-config로 병합을 확인합니다. 그러면 MCP 서버가 에이전트의 도구 목록에 mcp__tavily__tavily_search 등으로 나타납니다.

B. (선택 사항) DSH 설정에 대시보드 임베드

examples/dsh-integration/client-tavily-panel/을 디스크의 아무 곳에나 복사합니다. 예제는 @deepseek-ai/dsh-client-ui-slots의 settings.section 슬롯을 사용합니다 — 플러그인은 fetch를 통해 대시보드를 호출하는 Tavily 号池 패널을 등록합니다. 설치 방법:

1. 패키지 배치 (예: ~/.dsh/plugins/client-tavily-panel/).

2. 프로필의 node_modules에 링크하여 require.resolve가 찾을 수 있도록 합니다 (DSH는 패키지 이름 확인 체인을 통해 클라이언트 플러그인을 로드합니다):

   New-Item -ItemType Junction `
     -Path "$env:DSH_HOME\profiles\node_modules\dsh-client-tavily-panel" `
     -Target "C:\Users\ASUS\.dsh\plugins\client-tavily-panel"

   접합(심볼릭 링크 아님)은 관리자 권한이 필요하지 않습니다. 이 단계를 건너뛰고 pnpm add로 패키지를 로컬에 추가해도 괜찮습니다. 단, pnpm이 프로필의 다른 관련 없는 file: / GitHub 소스 의존성에서 멈출 수 있으므로 주의하세요.

3. cordis.patch.yml에 로스터 항목 추가:

   - insert:
       - id: client-tavily-panel
         name: 'dsh-client-tavily-panel'

4. dsh 웹 재시작. (함정 #6 참조 — 웹 프로필의 경우 HMR이 의도적으로 비활성화되어 있습니다. 패치 변경 사항은 전체 재시작 시에만 로드됩니다.)

재시작 후 ⚙️ 설정을 열면 왼쪽 탐색에 Tavily 号池 항목이 나타납니다.

DeepSeek 통합 중 발생한 함정들

다음은 제가(원래 통합자) 겪은 실제 오류입니다. 시작하기 전에 아래 순서대로 읽어보세요 — 각각 시간을 낭비했습니다.

함정 #1: mcp SDK 버전 관리

mcp_server.py는 from mcp.server.fastmcp import FastMCP를 사용합니다. 해당 모듈은 mcp 2.0에서 제거되었습니다 (FastMCP 구현이 별도의 fastmcp 패키지로 이동했으며 API가 다릅니다). pip install mcp로 최신 버전을 설치하면 MCP 서버가 시작되지 않습니다:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

고정:

# requirements.txt
mcp>=1.0.0,<2.0.0

mcp 1.29.0에서 테스트됨.

함정 #2: tavily_research는 비동기이며 생성 키에 바인딩됨

세 가지 하위 버그가 하나로:

• tavily-python SDK는 research()의 첫 번째 위치 인수를 query에서 input으로 이름을 변경했습니다. client.research(query=…)를 호출하면 missing 1 required positional argument: 'input' 오류가 발생합니다.

• SDK는 런타임에 model ∈ {"mini", "pro", "auto"}를 강제하지만, Tavily REST API 자체는 model=standard|pro를 허용합니다. standard를 전달하면 model must be one of: mini, pro or auto 오류가 발생합니다.

• research()는 즉시 status: pending 봉투를 반환합니다 — 실제 결과는 30–120초 이상 후에 도착합니다. get_research(request_id)를 status == "completed"가 될 때까지 반드시 폴링해야 합니다. 그렇지 않으면 도구가 항상 "pending"을 반환하고 모델은 호출이 실패했다고 생각합니다.

• 연구 작업은 이를 생성한 API 키에 바인딩됩니다. 풀의 다른 키는 결과를 가져올 수 없습니다(404 반환). 항상 동일한 TavilyClient 인스턴스로 폴링하세요 — 각 폴링 반복에서 pool.next_key()를 다시 호출하지 마세요. 그렇지 않으면 계속 잘못된 키를 치게 됩니다.

이 저장소의 tavily_research는 이미 전체 수명 주기를 래핑합니다: 최대 ~570초 동안 폴링한 다음 status: timeout 봉투와 request_id를 반환하여 호출자가 나중에 가져올 수 있도록 합니다. 두 번째 도구인 tavily_research_status(request_id)는 활성 키 목록을 탐색하여 임시 가져오기에 적합한 키를 찾습니다 — 도구 호출이 다른 프로세스에서 시간 초과되었을 수 있기 때문에 필요합니다.

함정 #3: Windows에서 dashboard.py UTF-8 읽기 버그

dashboard.py는 다음을 수행합니다:

DASHBOARD_HTML = TPL.read_text()

Path.read_text()는 기본적으로 locale.getpreferredencoding()을 사용하며, 이는 Windows(zh-CN)에서 GBK입니다. 번들된 templates/dashboard.html은 UTF-8이며 CJK 문자를 포함하므로 대시보드가 다음 오류를 발생시킵니다:

UnicodeDecodeError: 'gbk' codec can't decode byte 0xb6 in position 4308

수정:

DASHBOARD_HTML = TPL.read_text(encoding="utf-8")

함정 #4: run_*.sh의 크로스 플랫폼 경로

run_mcp.sh와 run_dashboard.sh는 .venv/bin/python3(Linux 규칙)을 하드코딩하며 Windows에서 테스트된 적이 없습니다. 스크립트 작성자는 또한 /home/user/code/Tavily를 사용하는 systemd 유닛을 제공했습니다 — 분명히 Linux 전용입니다.

Windows에서는 이러한 스크립트가 전혀 필요하지 않습니다. .venv\Scripts\python.exe를 직접 호출하면 됩니다(위 YAML 참조). 원래 Linux 사용 사례를 위해 저장소에 유지됩니다.

함정 #5: DSH 패치 구성은 시작 시에만 로드됨

cordis.patch.yml은 web 프로필이 부팅될 때 읽힙니다. 변경 사항은 핫 리로드되지 않습니다 — 웹 앱 번들 패치의 hmr 행이 의도적으로 비활성화되어 있습니다:

- id: hmr
  disabled: true
# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.

따라서 cordis.patch.yml을 편집한 후에는 dsh web을 재시작하세요 (안전하게 수행하는 방법은 함정 #6 참조).

dsh --profile web --dump-config를 사용하면 GUI를 실제로 부팅하지 않고도 패치가 올바르게 병합되는지 확인할 수 있습니다. 시작, GUI 확인, 종료, 수정, 반복보다 훨씬 빠릅니다.

함정 #6: 자살하지 않고 dsh web 재시작하는 방법

dsh web은 이 대화를 실행하는 호스트 프로세스이며, 도구 프로세스도 포함합니다. 동일한 dsh web이 생성한 pwsh에서 다음과 같이 실행하면:

Stop-Process -Id <dsh-web-pid> -Force
Start-Process dsh.cmd web

새 인스턴스가 시작되기 전에 명령 중간에 자살하게 됩니다. 처음 시도했을 때 PowerShell 세션이 exit code 4294967295로 중단되었고 아무 일도 일어나지 않았습니다.

해결책: 재시작을 Windows 작업 스케줄러에 맡깁니다. 작업 스케줄러는 svchost( dsh web이 아님) 아래에서 스크립트를 실행합니다:

$script = "$env:TEMP\dsh_restart.ps1"
@"
Start-Sleep -Seconds 8
Stop-Process -Id <dsh-web-pid> -Force
Get-CimInstance Win32_Process |
  Where-Object { `$_.CommandLine -match 'dsh web' } |
  ForEach-Object { Stop-Process -Id `$_.ProcessId -Force }
Start-Sleep -Seconds 3
Start-Process 'C:\…\dsh.cmd' web -WorkingDirectory 'H:\…' -WindowStyle Hidden
"@ | Out-File $script -Encoding utf8

schtasks /create /tn dsh-restart /tr "powershell -NoProfile -File $script" /sc once /st 23:59 /f
schtasks /run /tn dsh-restart
schtasks /delete /tn dsh-restart /f

그러면 이전 인스턴스가 죽기 전에 최종 답변을 반환할 시간이 약 8초 있습니다. 사용자에게 20–30초 후에 http://127.0.0.1:3080을 새로고침하라고 알립니다.

함정 #7: MCP 서버가 실행 중일 때 도구 디렉터리 마이그레이션

DSH의 mcp-client는 지수 백오프를 사용하여 연결이 끊어지면 다시 연결됩니다. (initialDelayMs 500, maxAttempts 10). Python 자식 프로세스를 종료하면 새 자식이 즉시 생성되며 재연결이 트리거됩니다. 그 후에 Move-Item으로 디렉터리를 이동하려고 하면 새 .venv\Scripts\python.exe가 파일을 잠그고 있어 robocopy가 [Result: 32] / "다른 프로세스에서 사용 중" 오류와 함께 실패합니다.

두 가지 실행 가능한 전략:

• 먼저 복사한 후, 원본을 삭제합니다. Copy-Item은 Windows 파일 공유를 통해 잠긴 파일을 읽습니다. 독점적인 접근이 필요하지 않습니다. 복사가 성공한 후, 이전 MCP 서버를 종료하고 원본을 제거합니다. pyvenv.cfg의 home = 줄이 동일한 기본 Python 설치를 가리키는 한 .venv는 완전히 재배치 가능합니다.

• 루프 종료 + robocopy /MOVE를 백오프 윈도우 내에서 성공할 때까지 반복합니다. 지저분하지만 작동합니다.

원래 마이그레이션은 다음을 사용했습니다:

Copy-Item -Path D:\Downloads\Tavily -Destination C:\Users\ASUS\.dsh\tavily-pool -Recurse -Force
# verify copy
Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'python.exe' -and $_.CommandLine -match 'mcp_server' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
# loop until deletion succeeds
for ($i=0; $i -lt 8; $i++) {
  Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'mcp_server' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
  Start-Sleep -Milliseconds 200
  Remove-Item D:\Downloads\Tavily -Recurse -Force -ErrorAction SilentlyContinue
  if (-not (Test-Path D:\Downloads\Tavily)) { break }
  Start-Sleep -Seconds 2
}

함정 #8: pnpm add가 관련 없는 종속성에서 멈출 수 있음

dsh plugin --profile web add <dir>을 실행하여 로컬 플러그인을 설치하면, pnpm은 전체 프로필 워크스페이스를 확인합니다. 여기에는 package.json에 나열된 GitHub 소스 또는 HTTP 소스 번들이 포함됩니다. 프로필에 이미 dsh-files: https://codeload.github.com/...tar.gz/...와 같은 항목이 포함되어 있고 해당 다운로드가 (방화벽, DNS, 콜드 캐시, 레지스트리 할당량으로 인해) 중단되면, 로컬 플러그인이 설치되지 않고 pnpm이 전체 타임아웃 동안 멈춥니다.

해결 방법: pnpm을 건너뛰고 직접 해결 방법을 생성합니다:

New-Item -ItemType Junction `
  -Path "$env:DSH_HOME\profiles\node_modules\dsh-client-tavily-panel" `
  -Target "<absolute path to your plugin package>"

정크션(심볼릭 링크가 아님)은 관리자 권한 없이 작동하며 require.resolve에 대해 동일하게 동작합니다. 그런 다음 패치 레이어는 pnpm이 설치한 것처럼 정확히 패키지를 name 필드로 참조합니다.

함정 #9: 설정 패널 클라이언트 플러그인 형식

자체 DSH 클라이언트 플러그인(브라우저 측)을 작성하는 경우, 런타임 형식은 ESM도, Cordis-from-source도 아닙니다. dsh-client-modules 플러그인은 작은 인메모리 모듈 로더를 호스팅하고 각 클라이언트 번들을 /plugins/<id>/client.js에서 가져옵니다. 번들은 다음을 호출해야 합니다:

window.__ModuleLoader__.load({
  id: "your-package-name",   // matches package.json "name"
  factory: (require) => {
    var module = { exports: {} };
    var exports = module.exports;
    var react = require("react");           // available
    var jsx = require("react/jsx-runtime"); // available
    // ... define components ...
    function apply(ctx) {
      ctx.slots.inject("settings.section", () => ctx.slots.register({
        name: "settings.section",
        id: "your-id",
        order: 100,
        label: "Your Label"
      }, YourComponent));
    }
    exports.apply = apply;
    exports.inject = ["slots"];             // services you depend on
    return module.exports;
  }
});

그리고 package.json에는 다음이 포함되어야 합니다:

{
  "main": "lib/index.js",
  "exports": { "./client": { "default": "./lib/client.js" } },
  "dsh": { "client": { "inject": ["@deepseek-ai/dsh-client-ui-slots"], "platform": "web" } }
}

lib/index.js는 호스트 진입점입니다. 서버 측에서 실행되며, no-op(function apply() {}; export { apply };)일 수 있습니다.

보안

• 휴지 상태의 일반 텍스트 키. tavily_keys.db는 Tavily API 키를 일반 텍스트로 저장합니다. SQLite 기반 풀이 모든 요청에 대해 쿼리되기 때문입니다. 파일 시스템 권한(Linux: chmod 600)으로 파일을 보호하세요. tavily_keys.db를 절대 커밋하지 마십시오(.gitignore 참조).

• 기본적으로 루프백 전용 대시보드. dashboard.py는 127.0.0.1:8000에 바인딩됩니다. LAN에 노출하는 경우 즉시 인증을 추가하십시오.

• CORS는 의도적으로 널리 열려 있습니다. 대시보드는 동일한 호스트의 포함된 UI에 의해 호출되도록 설계되었습니다. 루프백 바인드로 인해 안전하지만, 바인드 주소를 변경하는 경우 CORSMiddleware.allow_origins를 좁혀 일치시키십시오.

• 유출된 키 교체: python cli.py remove tvly-xxxxxxxx****yyyy, Tavily 대시보드에서 해지하고, 풀의 각 행에 대해 반복합니다.

문제 해결

크레딧

풀 관리 코드(key_pool.py, dashboard.py, FastMCP mcp_server.py 스켈레톤, cli.py)는 원래 익명의 작성자가 작성하여 공개적으로 공유했습니다. 이 저장소는 다음을 추가합니다:

• mcp 1.x 호환성(query→input, model 매핑, 연구 폴링).

• 비동기 가져오기를 위한 새로운 tavily_research_status 도구.

• Windows 크로스 플랫폼 수정(dashboard.py의 UTF-8 읽기).

• DSH용 드롭인 설정 패널 클라이언트 플러그인 및 위의 통합 함정 로그.

원저작자를 아는 경우, 크레딧을 추가할 수 있도록 이슈를 열어 주십시오.

라이선스

MIT. LICENSE를 참조하십시오.