ツール API と MCP サーバー

Bluesky.bot のツールは、コードや AI エージェントからも無料で使えます。REST API として、また MCP サーバーのツールとして提供しています。登録もキーも不要で、そのまま呼び出せます。どの回答にもツールのページへのリンクが付きます。

エンドポイント

ツールAPIMCP ツール
DID 検索GET /api/v1/tools/did-finder?handle=…find_did
ハンドル検索GET /api/v1/tools/handle-finder?did=…find_handle
whoisGET /api/v1/tools/whois?actor=…whois_lookup
アカウント年齢GET /api/v1/tools/account-age?actor=…check_account_age
AT URI コンバーターGET /api/v1/tools/at-uri-converter?uri=…convert_at_uri
TID デコーダーGET /api/v1/tools/tid-decoder?tid=…decode_tid
投稿の文字数カウンターGET /api/v1/tools/character-counter?text=…&numbered=truecount_post_characters
リッチテキストのファセットビルダーGET /api/v1/tools/facet-builder?text=…&langs=enbuild_post_facets
独自ドメインのハンドルチェッカーGET /api/v1/tools/custom-handle-checker?domain=…&expected=…check_custom_handle
ハンドルの空き状況チェッカーGET /api/v1/tools/handle-availability?name=…check_handle_availability
PLC 履歴GET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=falseplc_history
スターターパック分析GET /api/v1/tools/starter-pack-analyser?q=…analyse_starter_pack
投稿とスレッドのビューアGET /api/v1/tools/post-viewer?post=…&embed=falseview_bluesky_post
フィードインスペクターGET /api/v1/tools/feed-inspector?feed=…&check=falseinspect_bluesky_feed

ベース URL は https://bluesky.bot/api/v1 です。各ツールのパラメーターと回答は、API リファレンスと OpenAPI ドキュメント /api/v1/openapi.json に載っています。

回答の形はいつも同じです。ツールのスラッグ、そのページの URL、そして result です。

json
{
  "tool": "character-counter",
  "url": "https://bluesky.bot/tools/character-counter",
  "result": { "graphemes": 16, "bytes": 19, "over": false, "parts": [] }
}

制限

  • 無料・匿名: IP アドレスごとに 1 分あたり 60 回、1 日あたり 2,000 回。裏で複数のリクエストを送るツールは 1 回より多く数えられます。API リファレンスに記載しています。
  • API トークンあり: どちらも 10 倍で、アカウントごとに数えます。Bluesky.bot にボットが 1 つ以上あるクリエイターは、ダッシュボードの 設定 → API と CLI のアクセス で作成できます。コマンドラインツールのトークンも使えます。Authorization: Bearer <token> で送ってください。トークンの有効期間は 30 日です。公開するコードには含めないでください。
  • ダッシュボードのトークンでできること: ツールの呼び出しだけです。スコープは tools で、ボットの管理、ハンドルの取得や解放、CLI の /api/v1/me/* ルートの利用はできません(401 が返ります)。
  • 制限を超えると、回答は 429 で、Retry-After ヘッダーに待つ秒数が入ります。
  • 不明、期限切れ、または取り消されたトークンには 401 を返します。匿名で呼び出すにはヘッダーを外してください。

エラーは API のいつもの形 { "error": { "code", "message" } } で、bad_request(と parameter)、unauthorized、not_found、rate_limited、upstream_error(ツールが問い合わせるサービスが応答しなかった)があります。回答には CORS ヘッダーが付くので Web ページからも呼び出せます。キャッシュヘッダーも付き、カウンターのような純粋な計算は無期限にキャッシュされます。

例

テキストをエンコードしてくれる curl の場合:

bash
curl -G "https://bluesky.bot/api/v1/tools/character-counter" \
  --data-urlencode "text=Hello Bluesky! 👋"

JavaScript または TypeScript(Node.js 18 以降、Deno、Bun、ブラウザー)の場合:

tools-api.ts
// tools-api.ts:無料のツール API で投稿の文字数を数えます。キーは不要です。
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");

// ダッシュボードの設定で作成した API トークンを使うと、制限が 10 倍になります。
const token = process.env.BSBOT_TOKEN;
const response = await fetch(url, {
  headers: token ? { Authorization: `Bearer ${token}` } : {},
});
if (response.status === 429) {
  const wait = response.headers.get("Retry-After");
  throw new Error(`Rate limited: retry in ${wait} s.`);
}
const answer = (await response.json()) as {
  url: string;
  result: { graphemes: number; graphemesLeft: number; over: boolean };
};

const { graphemes, graphemesLeft } = answer.result;
console.log(`${graphemes} graphemes, ${graphemesLeft} left. ${answer.url}`);

// top-level await に必要なので、このファイルを ES モジュールにします。
export {};

Python で requests を使う場合:

tools-api.py
# tools_api.py:無料のツール API で投稿の文字数を数えます。キーは不要です。
import os

import requests

# ダッシュボードの設定で作成した API トークンを使うと、制限が 10 倍になります。
token = os.environ.get("BSBOT_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}

response = requests.get(
    "https://bluesky.bot/api/v1/tools/character-counter",
    params={"text": "Hello Bluesky! 👋"},
    headers=headers,
    timeout=10,
)
if response.status_code == 429:
    wait = response.headers["Retry-After"]
    raise SystemExit(f"Rate limited: retry in {wait} s.")
response.raise_for_status()

answer = response.json()
result = answer["result"]
print(f"{result['graphemes']} graphemes, {result['graphemesLeft']} left. {answer['url']}")

MCP サーバー

MCP サーバーは、同じツールを入力と出力のスキーマ付きで、AI エージェントやエディター向けに公開しています:https://bluesky.bot/api/mcp(Streamable HTTP、セッションなし)。すべてのツールは読み取り専用です。同じ制限が適用され、Authorization ヘッダーにトークンを入れると上がります。

ワンクリックで接続

トークンを貼り付ける代わりにサインインしたい場合は、https://bluesky.bot/api/mcp/connect を追加してください。AI アプリが Bluesky.bot のページを開くので、Bluesky アカウントでサインインし(パスワードを求めることはありません)、アプリの名前と戻り先のアドレスを確認して許可します。アプリは自分専用のトークンを受け取り、自動で更新します。

Claude Code の場合:

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connect

Claude Desktop や claude.ai では、この URL でカスタムコネクターを追加して 接続 を選びます。Cursor や VS Code では、下の設定の url にこの URL を入れ、エディターに求められたらサインインします。

  • アプリには tools スコープが与えられます。ツールを使え、Bluesky.bot にボットがあればアカウントの高い制限が適用されます。投稿、ボットの管理、ハンドルの取得はできません。
  • 許可したアプリは記憶されます。設定 → 接続済みアプリ でいつでも取り消せます。すべての端末でサインアウト やアカウントの削除で、すべてのアプリが取り消されます。
  • 確認済み と表示されるのは、よく知られた一部のアプリだけです。それ以外のアプリでは、許可する前に戻り先のアドレスを確認してください。
  • https://bluesky.bot/api/mcp はサインインなしでも引き続き使えます。

Claude Code の場合:

bash
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp

Cursor(.cursor/mcp.json)、VS Code(.vscode/mcp.json、"mcpServers" の代わりに "servers")、その他の多くのクライアントの場合:

json
{
  "mcpServers": {
    "bluesky-bot": { "url": "https://bluesky.bot/api/mcp" }
  }
}

Claude Desktop や claude.ai では、同じ URL でカスタムコネクターとして追加します。トークンを使うときはヘッダーを追加します。Claude Code なら --header "Authorization: Bearer $BSBOT_TOKEN"、JSON の設定なら url の隣に "headers": { "Authorization": "Bearer …" } です。トークンを含む設定ファイルはリポジトリにコミットしないでください。トークンは環境変数か、クライアントの非公開の設定に置いてください。

送られるもの、残るもの

ツールに送った内容は回答のためだけに使われます。保存されることはなく、エラーレポートからも取り除かれます。API の呼び出しでは入力がアドレスに入ります。当サーバーのリクエストログはこうしたアドレスを記録しませんが、サイトの通信を運ぶ Cloudflare のネットワークは通過します。MCP は入力をリクエストの本文で送り、本文はどのリクエストログにも残りません。機密性のあるテキストには MCP を選ぶこともできます。統計で数えるのは、どのツールが、どこから(ページ、API、MCP)呼ばれ、どう終わったかだけです。何かを調べるツールは、ページと同じように、必要な公開サービスに入力を送ります。詳しくはプライバシーポリシーをご覧ください。