textbee SMS

@textbee/mcp

textbee.dev 用の MCP サーバーです。textbee.dev は、Android スマートフォンを SMS API に変えるオープンソースの SMS ゲートウェイです。Claude、Cursor、その他のあらゆる MCP クライアントから、自分のスマートフォンと電話番号を使って SMS を送受信できます。

ツールは 3 つで、メッセージごとのマークアップ料金はなく、セルフホストの textbee インスタンスにも対応しています。

セットアップ

ペアリング済みの Android デバイスがある textbee アカウントと、ダッシュボードで取得した API キーが必要です。このキーはアカウント全体にアクセスできるため、パスワードと同様に扱ってください。

claude.ai、Claude Desktop、Claude モバイルアプリ（インストール不要）

これらは、同じパッケージのツールを実行するホスト型エンドポイント https://mcp.textbee.dev/mcp を使用します。

1. claude.ai または Claude Desktop で、Customize、Connectors、+ Add、Add custom connector の順に開きます。
2. 名前に textbee、URL に https://mcp.textbee.dev/mcp を入力し、Continue を 2 回クリックします。
3. Sign in now を選び、OAuth クライアントは推奨オプションのままにして、Add をクリックします。
4. textbee のサインインページで API キーを貼り付け、Connect をクリックします。

1 回接続すれば、ウェブ、Claude Desktop、Claude モバイルアプリで使用できます（モバイルアプリからコネクターを追加することはできません）。Team プランと Enterprise プランでは、まずオーナーが組織にコネクターを追加します。接続は 90 日間有効で、その後 Claude から再接続を求められます。textbee はキーを確認しますが、保存はしません。ただし、キーは textbee のサーバーを経由します。接続を解除するには、ダッシュボードでキーを失効させてください。キーを自分のマシンに保持するには、以下のローカルセットアップを使用してください。

Claude Code

キーを自分の設定に保存するローカル接続：

claude mcp add textbee -s user -e TEXTBEE_API_KEY=your-key -- npx -y @textbee/mcp

または、ブラウザーでキーを使ってサインインするホスト型接続：

claude mcp add --transport http -s user textbee https://mcp.textbee.dev/mcp

その後、Claude Code で /mcp を実行し、textbee を選択して、Authenticate を選びます。

Claude Desktop（ローカル）

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json、Windows：%APPDATA%\Claude\claude_desktop_config.json）に追加してから、Claude Desktop を再起動します。

{
  "mcpServers": {
    "textbee": {
      "command": "npx",
      "args": ["-y", "@textbee/mcp"],
      "env": { "TEXTBEE_API_KEY": "your-key" }
    }
  }
}

Cursor

同じオブジェクトを ~/.cursor/mcp.json に追加します。ヘッダー付きのリモートサーバーに対応するクライアントでは、代わりに https://mcp.textbee.dev/mcp を使用し、キーを x-textbee-api-key または Authorization: Bearer <key> として送信できます。

詳しいセットアップガイド：textbee.dev/docs/agents/mcp。

初回起動が遅い場合

初回実行時に npx がパッケージをダウンロードします。クライアントが待機中にタイムアウトする場合は、グローバルに一度インストールして、設定でバイナリを指定してください。

npm install -g @textbee/mcp

{ "mcpServers": { "textbee": { "command": "textbee-mcp", "env": { "TEXTBEE_API_KEY": "your-key" } } } }

ツール

send_sms

1 人以上の宛先に SMS を送信します（E.164 形式。例：+15550100123）。送信に使うスマートフォンは自動的に選択されます。既定のデバイスがあればそれを使い、なければ有効なデバイスのうち最後のハートビートが最も新しいものを使います。device_id、sim_subscription_id、scheduled_at は任意です。アカウントで SMS キューを使用している場合、配信状況の確認に使う sms_batch_id が返されます。

get_messages

アカウント内のすべてのデバイスにまたがってメッセージを読み取ります。既定では受信メッセージを新しい順に取得します。direction（received、sent、all）、フリーテキストの search、sms_batch_id（送信ごとの宛先別配信状況）、device_ids、および from／to による期間で絞り込めます。重複や欠落なしでポーリングできるカーソルページネーションに対応しています。

list_devices

アカウントに登録されているスマートフォンの一覧を取得します。ID、有効状態、既定の送信デバイス、最終チェックイン時刻、メッセージ数が含まれます。

セルフホスト版 textbee

サーバーを独自のインスタンスに接続します。

"env": {
  "TEXTBEE_API_KEY": "your-key",
  "TEXTBEE_BASE_URL": "https://sms.example.com"
}

/api/v1 のサフィックスは省略可能で、自動的に追加されます。https://example.com/textbee のようなサブパスへのデプロイにも対応しています。無効な URL はエラーになり、サイレントフォールバックは行われないため、URL を入力し間違えてもキーがパブリック API に送信されることはありません。

環境変数

変数	必須	デフォルト	用途
TEXTBEE_API_KEY	はい	なし	textbee ダッシュボードで取得した API キー
TEXTBEE_BASE_URL	いいえ	https://api.textbee.dev	セルフホストする場合のインスタンスの URL
TEXTBEE_TIMEOUT_MS	いいえ	30000	リクエストごとのタイムアウト（ミリ秒）

注意事項

• キーはご利用のマシンに保存されます。このサーバーは、上記のベース URL にある textbee API とのみ通信します。
• メッセージの送信数は textbee のプランの利用枠にカウントされ、プランのレート制限がサーバー側で適用されます。
• 診断情報はすべて stderr に出力されます。stdout は MCP プロトコル専用です。

ライブラリとしての使用

このパッケージは、別の MCP ホストに組み込むためのツール定義もエクスポートします（ホスト型リモートエンドポイントは、この方法でツール定義を再利用しています）。

import { createTextbeeMcpServer, staticCredentials, loadConfig } from '@textbee/mcp'

const server = createTextbeeMcpServer({
  credentials: staticCredentials(loadConfig(process.env)),
})

認証情報はツール呼び出しごとに解決されるため、マルチテナントホストではリクエストごとに異なるキーを渡せます。credentialsFromAuthInfoExtra を参照してください。

ライセンス

MIT。textbee プロジェクトの一部です。