Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
이 패키지는 Claude, ChatGPT 등 다양한 AI 클라이언트를 위한 웹 검색, 페이지 가져오기 및 브라우저 자동화 기능을 제공하는 리버스 프록시 서버입니다. 로컬 엔드포인트를 통해 호스팅된 TinyFish MCP 서버에 연결하며, 28개의 도구를 활용하여 에이전트 워크플로우를 확장할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기TinyFish MCP 서버: Claude, Cursor, VS Code 및 모든 MCP 클라이언트를 위한 웹 검색, 페이지 가져오기 및 추출, 브라우저 자동화 및 페이지 모니터링.
검색(Search)과 가져오기(Fetch)는 무료입니다.
Claude 또는 ChatGPT를 브라우저나 데스크톱 앱에서 사용하십니까? 설정 과정을 건너뛰고 단 한 번의 클릭으로 공식 TinyFish 플러그인을 사용하여 Claude 또는 **ChatGPT**를 추가하세요. 이 플러그인은 준비된 스킬과 안전 규칙을 포함하여 이러한 도구들을 묶어 제공합니다.
이 패키지는 투명한 리버스 프록시(reverse proxy)로, 로컬 Streamable-HTTP MCP 엔드포인트인 http://127.0.0.1:3711/mcp를 노출하고 모든 요청을 호스팅된 TinyFish MCP 서버(https://agent.tinyfish.ai/mcp)로 전달합니다.
이 프록시는 자체적인 도구나 스키마를 정의하지 않습니다. tools/list, tools/call, resources/*, 오류, 그리고 run_web_automation SSE 진행 스트림은 모두 호스팅된 서버에서 가져옵니다: 스트리밍(SSE) 응답은 바이트 단위로 그대로 전달되며, 비스트리밍 JSON 응답은 내용이 동일하게 전달됩니다 (파싱 후 재직렬화되어 업스트림과 깊이가 같습니다). 호스팅된 서버가 말하는 것이 클라이언트가 보는 것입니다.
호스팅된 서버는 28개의 도구를 노출합니다. 이 도구들을 사용하여 웹 검색, 페이지 가져오기 및 추출, 브라우저 자동화, 원격 Chrome 세션 실행(CDP), 로그인 상태를 유지하는 브라우저 컨텍스트 프로필 관리, 그리고 페이지 및 주제 모니터링을 예약할 수 있습니다.
| 카테고리 | 도구 |
|---|---|
| 검색 & 가져오기 (Search & Fetch) | search, fetch_content |
| ... |
MCP 클라이언트가 원격 Streamable-HTTP 서버(Claude Code, Claude Desktop 커넥터, Cursor, VS Code 및 대부분의 최신 클라이언트)를 지원하는 경우, 설치 과정이나 로컬 프로세스 없이 직접 호스팅된 서버에 연결하세요:
이 패키지를 대신 사용해야 하는 경우:
npm install -g @tiny-fish/mcp
또는 설치 없이 실행할 수 있습니다:
npx @tiny-fish/mcp
Node.js >= 22가 필요합니다. (이는 TinyFish CLI의 >=24 요구 사항과 의도적인 차이점입니다 — 여기서는 Node 24가 필요한 부분이 없습니다.)
서버는 시작 시 환경 변수에서 TINYFISH_API_KEY를 읽고, 모든 호출에 대해 이를 X-API-Key로 상위(upstream) 전송합니다. 키는 https://agent.tinyfish.ai에서 받으세요.
export TINYFISH_API_KEY=tf_...
tinyfish-mcp
성공적으로 실행되면 표준 에러(stderr)에 한 줄이 출력됩니다:
tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0
키는 절대 기록되거나 클라이언트로 반향(echo)되지 않습니다.
tinyfish-mcp를 실행한 후 (예: 터미널에서, 또는 원하는 프로세스 관리자 아래서), 클라이언트를 http://127.0.0.1:3711/mcp로 지정하세요.
claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp
설정 → 커넥터 → 사용자 지정 커넥터 추가에서 URL을 http://127.0.0.1:3711/mcp로 설정합니다. claude_desktop_config.json이 URL 기반 서버를 지원하는 버전의 경우:
{
### VS Code
`.vscode/mcp.json`:
```json
{
"servers": {
"tinyfish": {
...
Streamable-HTTP (원격/URL) MCP 서버를 다음을 사용하여 구성합니다:
{ "url": "http://127.0.0.1:3711/mcp" }
이 엔드포인트는 POST /mcp만 허용하며 (호스팅된 서버와 일치함. 이 서버는 GET SSE 채널이나 DELETE 세션 종료 기능이 없음). 디버깅을 위해 GET /healthz를 요청하면 200 ok가 반환됩니다.
| 변수 (Variable) | 기본값 (Default) | 설명 (Description) |
|---|---|---|
TINYFISH_API_KEY | (필수) | TinyFish API 키. 상위 시스템으로 X-API-Key로 전송됩니다. 이 키가 없으면 서버는 시작을 거부합니다. |
| ... |
프록시는 또한 모든 상위 호출에 속성(attribution headers)을 전송합니다:
X-TF-Request-Origin: tinyfish-mcp, X-TF-Client-Name: tinyfish-mcp, 그리고
X-TF-Client-Version: <패키지 버전>.
이 서버는 의도적이고 문서화된 신뢰 경계(trust boundary)를 가진 루프백 전용(loopback-only) 서버입니다:
127.0.0.1 리터럴에 바인딩되며 이는 설정할 수 없습니다. 절대 0.0.0.0이나 LAN 인터페이스에서 리스닝 할 수 없습니다.Origin 헤더를 포함하는 요청은 Origin이 http(s)://127.0.0.1 또는 http(s)://localhost (모든 포트)가 아닌 경우 403으로 거부됩니다. 이는 MCP 사양에서 로컬 HTTP 서버에 대해 지적한 DNS-재바인딩 공격을 차단합니다. Origin 헤더가 없는 요청(curl, MCP SDK 등 인스펙터)은 허용됩니다.TINYFISH_API_KEY를 읽고, 클라이언트는 로컬 호프에서 어떤 자격 증명도 전송하지 않습니다. 이는 가장 간단한 모델이지만, 127.0.0.1:<포트>에 도달할 수 있는 모든 로컬 프로세스가 귀하의 키를 사용하여 자동화를 실행할 수 있다는 것을 의미합니다 (이는 TinyFish 크레딧을 소모할 수 있습니다). 루프백 바인드와 Origin 체크가 완화책(mitigations)입니다. 이 포트를 신뢰하는 장치에서의 로컬 신뢰 경계로 간주하십시오."Port 3711 is already in use" — 다른 프로세스가 해당 포트를 사용 중입니다. 해당 프로세스를 중지하거나, PORT를 사용 가능한 다른 포트로 설정하고 클라이언트 설정을 업데이트하세요.
HTTP 502와 JSON-RPC 오류 -32001 ("Upstream rejected the request … check that TINYFISH_API_KEY is set to a valid TinyFish API key") — 호스팅된 서버가 사용한 키를 거부했습니다. tinyfish-mcp 프로세스의 환경 변수에 TINYFISH_API_KEY가 설정되어 있는지(단지 쉘에만 설정된 것이 아닌지) 그리고 해당 키가 https://agent.tinyfish.ai에서 유효한지 확인하세요. 오류의 data 필드에는 업스트림 상태와 진단을 위한 (절단된) 본문이 담겨 있습니다.
HTTP 502와 JSON-RPC 오류 -32000 ("cannot reach …") — 업스트림 서버에 연결할 수 없습니다: 네트워크/프록시/VPN을 확인하세요. 호스팅된 서버가 일시적으로 다운되었을 수도 있습니다. 만약 TINYFISH_UPSTREAM_URL을 재정의했다면, 그것을 확인하세요. 스트리밍되는 run_web_automation 호출이 중간에 실패하면 최종 SSE 프레임과 동일한 -32000 오류가 발생하며,
통합 테스트는 실제 호스팅된 업스트림에 도달하며, 다음 조건이 충족되어야 실행됩니다: TINYFISH_API_KEY가 없으면 경고 메시지를 출력하고 건너뜁니다.
TINYFISH_API_KEY=... npm run test:integration
테스트 대상이 프로덕션 대신 샌드박스 배포를 가리키도록 TINYFISH_UPSTREAM_URL을 설정하세요. 특히, run_web_automation 통합 테스트는 실제 자동화를 실행하며 크레딧을 소모한다는 점에 유의하십시오.
@Zechereh가 유지보수합니다. 버그 및 기능 요청: GitHub 이슈.
MIT