TinyFish

@tiny-fish/mcp

TinyFish MCP サーバー：Claude、Cursor、VS Code、およびあらゆる MCP クライアント向けのウェブ検索、ページ取得と抽出、ブラウザー自動化、ページ監視機能です。検索と取得は無料です。

ブラウザーまたはデスクトップアプリで Claude や ChatGPT を使っていますか？ セットアップは不要です。公式の TinyFish プラグインを Claude または ChatGPT にワンクリックで追加してください。すぐに使えるスキルと安全ルールを備えた これらのツールが含まれています。

このパッケージは透過的なリバースプロキシです。ローカルの 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）の実行、サインイン済みの Browser Context Profiles の維持、ページやトピックの Monitor のスケジュール設定に使用できます。

カテゴリー	ツール
検索と取得	search, fetch_content
ウェブ自動化	run_web_automation, run_web_automation_async, get_run, list_runs, cancel_run, batch_status, batch_cancel
ブラウザーセッション	create_browser_session, list_browser_sessions, close_browser_session
Browser Context Profiles	create_profile, list_profiles, start_profile_setup_session, save_profile_setup_session, cancel_profile_setup_session
Monitor	create_monitor, get_monitor, list_monitors, run_monitor, pause_monitor, resume_monitor, cancel_monitor
アカウントと使用状況	get_wallet, get_search_usage, list_fetch_usage, guide_next_step

• ツールのリファレンス：すべてのツールのパラメーターを原文のまま掲載
• 例：一般的なワークフローとプロンプト
• MCP 統合ガイド：クライアントの設定、認証、利用制限、トラブルシューティング
• ドキュメント全文：docs.tinyfish.ai

まずはホスト型サーバーをお試しください

MCP クライアントがリモートの Streamable-HTTP サーバーに対応している場合（Claude Code、 Claude Desktop のコネクター、Cursor、VS Code、およびほとんどの最新クライアントが対応しています）、 ホスト型サーバーに直接接続できます。インストールもローカルプロセスも不要です。

https://agent.tinyfish.ai/mcp

次のような場合は、このパッケージを使用してください。

• クライアントがローカル MCP サーバーとの通信にしか対応していない場合、または
• ホスト型サーバーの OAuth フローではなく、環境変数に設定した TinyFish API key で 認証したい場合（CI、ヘッドレスマシン、スクリプトなど）。

インストール

npm install -g @tiny-fish/mcp

または、インストールせずに実行できます。

npx @tiny-fish/mcp

Node.js >= 22 が必要です。（これは TinyFish CLI の >=24 要件から意図的に変更しています。このパッケージでは Node 24 は必要ありません。）

API キー

サーバーは起動時に環境変数 TINYFISH_API_KEY を読み込み、すべての呼び出しで X-API-Key として上流に送信します。キーは https://agent.tinyfish.ai で取得できます。

export TINYFISH_API_KEY=tf_...
tinyfish-mcp

成功すると、stderr に次の 1 行が出力されます。

tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0

キーがログに記録されたり、クライアントに返されたりすることはありません。

クライアントの設定

tinyfish-mcp を起動し（ターミナルで実行するか、任意のプロセスマネージャーで起動します）、クライアントを http://127.0.0.1:3711/mcp に接続します。

Claude Code

claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp

Claude Desktop

Settings → Connectors → Add custom connector で、URL に http://127.0.0.1:3711/mcp を指定します。 claude_desktop_config.json が URL ベースのサーバーに対応しているバージョンの場合：

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

注：Claude Desktop では、ホストされた https://agent.tinyfish.ai/mcp をカスタムコネクターとして直接使用することもできます。API キー認証が必要な場合を除き、こちらを推奨します。

Cursor

~/.cursor/mcp.json（またはプロジェクト内の .cursor/mcp.json）：

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

VS Code

.vscode/mcp.json：

{
  "servers": {
    "tinyfish": {
      "type": "http",
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

その他のクライアント

次の設定で、Streamable-HTTP（リモート／URL）MCP サーバーを構成します。

{ "url": "http://127.0.0.1:3711/mcp" }

エンドポイントが受け付けるのは POST /mcp のみです（GET SSE チャネルと DELETE によるセッション終了処理がない、ホストされたサーバーと同じ仕様です）。デバッグ用に、GET /healthz は 200 ok を返します。

環境変数

変数	デフォルト	説明
TINYFISH_API_KEY	（必須）	TinyFish API キー。上流には X-API-Key として送信されます。設定されていない場合、サーバーは起動を拒否します。
PORT	3711	ローカルの待ち受けポート（整数、1～65535）。自動インクリメントは行われません。ポートが使用中の場合、サーバーはエラーで終了します。
TINYFISH_UPSTREAM_URL	https://agent.tinyfish.ai/mcp	上流の MCP URL。https: が必須です。http: が許可されるのは 127.0.0.1／localhost の場合のみです（ローカルテスト用）。

プロキシは、すべての上流呼び出しに次の帰属情報ヘッダーも送信します。 X-TF-Request-Origin: tinyfish-mcp、X-TF-Client-Name: tinyfish-mcp、および X-TF-Client-Version: <package version>。

セキュリティと信頼モデル

これは、意図的に定められた文書化済みの信頼境界を持つ、ループバック専用サーバーです。

• 常にループバックにバインドします。 サーバーは 127.0.0.1 のリテラルにバインドし、これは設定できません。0.0.0.0 や LAN インターフェイスで待ち受けることはありません。
• オリジンの検証。 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:<port> に接続できるローカルプロセスであれば、どれでもキーを使用して自動化を実行できます（TinyFish のクレジットが消費される場合があります）。対策はループバックへのバインドと Origin チェックです。信頼できるマシン上で、このポートをローカルの信頼境界として扱ってください。

トラブルシューティング

「ポート 3711 はすでに使用中です」 — 別のプロセスがそのポートを使用しています。そのプロセスを停止するか、PORT を未使用のポートに設定し、クライアント設定もそれに合わせて更新してください。

JSON-RPC エラー -32001 を伴う HTTP 502（「上流がリクエストを拒否しました……TINYFISH_API_KEY に有効な TinyFish API キーが設定されていることを確認してください」）— ホストされたサーバーがキーを拒否しました。tinyfish-mcp プロセスの環境で TINYFISH_API_KEY が設定されていること（シェルだけでなく）と、キーが https://agent.tinyfish.ai で有効であることを確認してください。診断用に、エラーの data には上流のステータスと（切り詰められた）本文が含まれます。

JSON-RPC エラー -32000 を伴う HTTP 502（「接続できません……」）— 上流サーバーに接続できません。ネットワーク／プロキシ／VPN を確認してください。ホストされたサーバーが一時的に停止している可能性もあります。TINYFISH_UPSTREAM_URL を上書きしている場合は、その値を確認してください。ストリーミング中の run_web_automation 呼び出しが途中で失敗した場合は、最終 SSE フレームで同じ -32000 が返され、「実行は継続中の可能性があります」という警告と、判明している場合は runId が含まれます。むやみに再試行せず、実行のステータスを確認してください。

バッチリクエストが動作しない — MCP では JSON-RPC のバッチ処理が禁止されており、ホストされたサーバーもバッチ配列に対応していません。プロキシはバッチをそのまま転送し、上流が独自のエラーを返します。リクエストごとに JSON-RPC メッセージを 1 つ送信してください。

Claude／その他のクライアントが接続できない — tinyfish-mcp が実際に実行中であること（これはスタンドアロンサーバーです。クライアントから起動されるものではありません）と、GET http://127.0.0.1:3711/healthz が ok を返すことを確認してください。

開発

npm ci
npm run build        # tsc → dist/, marks dist/index.js executable
npm test             # unit tests (offline, mock upstream)
npm run test:watch   # unit tests in watch mode
npm run lint         # eslint over src/ tests/
npm run format       # prettier
npm run type-check   # tsc --noEmit over the whole tree

構成：src/core/ はトランスポートに依存しないプロキシコア（上流クライアント、セッションブリッジ、SSE リレー、エラー整形）です。src/http/ は薄い HTTP アダプター（ルーティング、Origin チェック）です。tests/ にはユニットテスト一式と、ユニットテストが完全オフラインで実行される際に使用するホスト型エンドポイントのモック tests/helpers/mock-upstream.ts が含まれています。

統合テストは実際のホスト型上流に接続して実行され、条件付きで有効になります。TINYFISH_API_KEY がない場合は、通知を出力してスキップされます。

TINYFISH_API_KEY=... npm run test:integration

本番環境の代わりにサンドボックス環境を対象にするには、TINYFISH_UPSTREAM_URL を設定します。run_web_automation の統合テストでは実際の自動化が実行され、クレジットが消費されることに注意してください。

メンテナンス

@Zechereh がメンテナンスしています。バグ報告や機能リクエストはGitHub のイシューをご利用ください。

ライセンス

MIT