Firecrawl Simple MCP Server

Firecrawl Simple MCP サーバー

Firecrawl Simple 用の Model Context Protocol（MCP）サーバーです。LLM がウェブコンテンツにアクセスして処理できるようにする、強力なウェブスクレイピングおよびサイトマッピングツールです。

プロジェクトリンク

• GitHub リポジトリ
• npm パッケージ

目次

• 前提条件
• クイックスタート
• 機能
• インストール
• 使い方
• 設定
• 利用可能なツール
• トラブルシューティング
• クロール機能に関する注意
• アーキテクチャの改善
• 開発
• テスト
• コントリビューション
• ライセンス

前提条件

Firecrawl Simple MCP Server をインストールして使用する前に、以下を用意してください。

• Node.js 16.x 以降がインストールされていること
• 稼働中の Firecrawl Simple API インスタンスにアクセスできること
• グローバルにインストールする場合は、npm パッケージをグローバルにインストールするための十分な権限があること

クイックスタート

# Install the package
npm install -g firecrawl-simple-mcp

# Run with default configuration
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# Test with a simple scrape request
curl -X POST http://localhost:3003/mcp/tool \
  -H "Content-Type: application/json" \
  -d '{"name":"firecrawl_scrape","arguments":{"url":"https://example.com"}}'

機能

• ウェブスクレイピング：JavaScript のレンダリングに対応し、任意の URL からコンテンツをスクレイピングします。
• ウェブサイトのマッピング：指定したサイトのサイトマップを生成します。
• シンプルなアーキテクチャ：一貫したパターンと改善されたエラーハンドリングを備えた、最適化済みのコードベースです。
• 型安全性：Zod スキーマ検証により、コードベース全体で強い型付けを実現しています。
• 設定可能：環境変数を使って動作をカスタマイズできます。

インストール

npm を使用する

npm install -g firecrawl-simple-mcp

ソースからインストールする

git clone https://github.com/dsafonov/firecrawl-simple-mcp.git
cd firecrawl-simple-mcp
npm install
npm run build

使い方

サーバーの実行

# Basic usage with self-hosted Firecrawl Simple
FIRECRAWL_API_URL=http://localhost:3002/v1 firecrawl-simple-mcp

# With additional configuration
FIRECRAWL_API_URL=http://localhost:3002/v1 \
FIRECRAWL_LOG_LEVEL=DEBUG \
firecrawl-simple-mcp

設定

サーバーは環境変数を使って設定できます。

変数	説明	デフォルト
FIRECRAWL_API_URL	Firecrawl Simple API の URL	http://localhost:3002/v1
FIRECRAWL_API_KEY	認証用の API キー（必要な場合）	-
FIRECRAWL_API_TIMEOUT	API リクエストのタイムアウト（ミリ秒）	30000
FIRECRAWL_SERVER_PORT	SSE トランスポート使用時の MCP サーバーのポート	3003
FIRECRAWL_TRANSPORT_TYPE	トランスポートの種類（stdio または sse）	stdio
FIRECRAWL_LOG_LEVEL	ログレベル（DEBUG、INFO、WARN、ERROR）	INFO
FIRECRAWL_VERSION	バージョン識別子	1.0.0

Claude Desktop で使用する

以下を claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "firecrawl-simple-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-simple-mcp"],
      "env": {
        "FIRECRAWL_API_URL": "http://localhost:3002/v1"
      }
    }
  }
}

Cursor で使用する

Cursor で設定するには、以下の手順に従います。

1. Cursor の設定を開きます
2. Features > MCP Servers に移動します
3. 「+ Add New MCP Server」をクリックします
4. 次の内容を入力します。
   • Name：「firecrawl-simple-mcp」（または任意の名前）
   • Type：「command」
   • Command：env FIRECRAWL_API_URL=http://localhost:3002/v1 npx -y firecrawl-simple-mcp

利用可能なツール

1. スクレイピングツール（firecrawl_scrape）

JavaScript のレンダリングに対応し、単一の URL からコンテンツをスクレイピングします。

{
  "name": "firecrawl_scrape",
  "arguments": {
    "url": "https://example.com",
    "formats": ["markdown", "html", "rawHtml"],
    "waitFor": 1000,
    "timeout": 30000,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "headers": {
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "Accept-Language": "en-US,en;q=0.9"
    },
    "mobile": false
  }
}

パラメーター：

• url（必須）：スクレイピングする URL です。
• formats：返す出力形式の配列です。選択肢は「markdown」、「html」、「rawHtml」です。
• waitFor：JavaScript の実行を待機する時間（ミリ秒）です。
• timeout：リクエストのタイムアウト（ミリ秒）です。
• includeTags：結果に含める HTML タグです。
• excludeTags：結果から除外する HTML タグです。
• headers：リクエストとともに送信するカスタム HTTP ヘッダーです。
• mobile：モバイルのビューポートを使用するかどうかです。

2. Map ツール（firecrawl_map）

指定したサイトのサイトマップを生成します。

{
  "name": "firecrawl_map",
  "arguments": {
    "url": "https://example.com",
    "search": "optional search term",
    "ignoreSitemap": true,
    "includeSubdomains": false,
    "limit": 5000
  }
}

パラメーター：

• url（必須）：マッピングする URL です。
• search：URL を絞り込む検索語です。
• ignoreSitemap：sitemap.xml を無視するかどうかです。
• includeSubdomains：マッピングにサブドメインを含めます。
• limit：マッピングする URL の最大数です。

トラブルシューティング

よくあるエラーと解決方法

接続の問題

エラー：Failed to connect to Firecrawl API at http://localhost:3002/v1

解決方法：

• Firecrawl Simple API が実行中であることを確認します
• /v1 パスを含め、API URL が正しいことを確認します
• 接続を妨げるネットワーク制限がないことを確認します

認証エラー

エラー：Authentication failed: Invalid API key

解決方法：

• FIRECRAWL_API_KEY が正しいことを確認します
• API で認証が必要かどうかを確認します
• 有効な認証情報について、API 管理者に問い合わせます

タイムアウトエラー

エラー：Request timed out after 30000ms

解決方法：

• FIRECRAWL_API_TIMEOUT の値を増やします
• 対象のウェブサイトが遅い、または応答していないか確認します
• JavaScript の実行に時間をかけられるよう、waitFor パラメーターの使用を検討します

レート制限

エラー：Rate limit exceeded

解決方法：

• リクエストの頻度を下げます
• 独自のレート制限戦略を実装します
• レート制限の引き上げについて、API 管理者に問い合わせます

無効な URL エラー

エラー：Invalid URL format

解決方法：

• URL にプロトコル（http:// または https://）が含まれていることを確認します
• ドメイン名に誤字がないか確認します
• 通常のブラウザーで URL にアクセスできることを確認します

クロール機能に関する注意事項

この MCP サーバーでは、以下の理由によりクロール機能を意図的に削除しています。

1. コンテキスト管理：クロール機能は MCP サーバーのコンテキストに情報を過剰に提供するため、LLM のコンテキストがあふれる問題につながる可能性があります。複数のページをクロールすると大量のテキストが生成され、多くのモデルのコンテキスト制限を超えてしまうためです。

2. 非同期処理：クロールは非同期で実行されますが、MCP サーバーのアーキテクチャは同期的なリクエスト／レスポンスのパターンに最適化されているため、非同期処理は適していません。クロールの非同期性により、MCP の同期通信モデルとの統合が困難になります。

3. ドキュメントとの整合性：ユーザーにとって一貫性と明確さを保てるよう、利用可能なツールを主要なドキュメントに合わせました。

ウェブサイトのクロール機能が必要な場合は、複数の対象 URL に個別のスクレイプツールを使用するか、MCP サーバーの外部でカスタムソリューションを実装してください。

アーキテクチャの改善

コードベースは、いくつかの重要な改善によって最適化されています。

1. サービスレイヤーの簡素化

• 重複を減らした関数型のアプローチ。
• すべてのサービスメソッドで一貫したエラー処理。
• Zod スキーマを使用した厳密な入力検証。
• サービスとツールの責務を明確に分離。

2. エラー処理の強化

• エラー処理ユーティリティを一元化。
• ユーザー体験を向上させる、一貫したエラー形式。
• 適切なエラー分類（検証、API、ネットワーク、タイムアウト）。
• コンテキスト情報を含むエラーログの改善。
• LLM が利用しやすいエラーメッセージ。

3. 型安全性の改善

• 安全でない any 型を排除。
• 適切な型アサーションと検証を追加。
• 適切なエラーフラグを備えた、一貫した戻り値の型。
• 設定とツール入力に対する Zod スキーマ検証。

4. 設定管理

• 環境変数を堅牢に処理し、検証します。
• 設定が無効な場合は、妥当なデフォルト値にフォールバックします。
• 設定の問題を明確に示すエラーメッセージ。
• 設定モジュールを一元化。

5. コード構成

• 一貫したファイルとモジュールの構成。
• ツールと応答を作成するためのファクトリーパターン。
• API クライアントの使い方を簡素化。
• 責務の分離を改善。

開発

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run coverage

# Lint code
npm run lint

# Type check
npm run typecheck

テスト

このプロジェクトには、すべてのツールとサービスを対象とした包括的なテストが含まれています。テストを実行するには、次のようにします。

npm test

テストカバレッジレポートを生成するには、次のようにします。

npm run coverage

テストスイートには、次のテストが含まれています。

• すべての MCP ツールを対象としたユニットテスト。
• エラー処理のテスト。
• パラメーター検証のテスト。
• 入力検証のテスト。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします。
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）。
3. 変更をコミットします（git commit -m 'Add some amazing feature'）。
4. ブランチにプッシュします（git push origin feature/amazing-feature）。
5. プルリクエストを作成します。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。