ツール API と MCP サーバー
Bluesky.bot のツールは、コードや AI エージェントからも無料で使えます。REST API として、また MCP サーバーのツールとして提供しています。登録もキーも不要で、そのまま呼び出せます。どの回答にもツールのページへのリンクが付きます。
エンドポイント
| ツール | API | MCP ツール |
|---|---|---|
| DID 検索 | GET /api/v1/tools/did-finder?handle=… | find_did |
| ハンドル検索 | GET /api/v1/tools/handle-finder?did=… | find_handle |
| whois | GET /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=true | count_post_characters |
| リッチテキストのファセットビルダー | GET /api/v1/tools/facet-builder?text=…&langs=en | build_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=false | plc_history |
| スターターパック分析 | GET /api/v1/tools/starter-pack-analyser?q=… | analyse_starter_pack |
| 投稿とスレッドのビューア | GET /api/v1/tools/post-viewer?post=…&embed=false | view_bluesky_post |
| フィードインスペクター | GET /api/v1/tools/feed-inspector?feed=…&check=false | inspect_bluesky_feed |
ベース URL は https://bluesky.bot/api/v1 です。各ツールのパラメーターと回答は、API リファレンスと OpenAPI ドキュメント /api/v1/openapi.json に載っています。
回答の形はいつも同じです。ツールのスラッグ、そのページの URL、そして result です。
{
"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 の場合:
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:無料のツール 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:無料のツール 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']}")テキストは GET リクエストのアドレスに入るため、サーバーによっては約 8 KB で切られます。長いテキストには MCP サーバーを使ってください。入力をリクエストの本文で送ります。
MCP サーバー
MCP サーバーは、同じツールを入力と出力のスキーマ付きで、AI エージェントやエディター向けに公開しています:https://bluesky.bot/api/mcp(Streamable HTTP、セッションなし)。すべてのツールは読み取り専用です。同じ制限が適用され、Authorization ヘッダーにトークンを入れると上がります。
ワンクリックで接続
トークンを貼り付ける代わりにサインインしたい場合は、https://bluesky.bot/api/mcp/connect を追加してください。AI アプリが Bluesky.bot のページを開くので、Bluesky アカウントでサインインし(パスワードを求めることはありません)、アプリの名前と戻り先のアドレスを確認して許可します。アプリは自分専用のトークンを受け取り、自動で更新します。
Claude Code の場合:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connectClaude Desktop や claude.ai では、この URL でカスタムコネクターを追加して 接続 を選びます。Cursor や VS Code では、下の設定の url にこの URL を入れ、エディターに求められたらサインインします。
- アプリには
toolsスコープが与えられます。ツールを使え、Bluesky.bot にボットがあればアカウントの高い制限が適用されます。投稿、ボットの管理、ハンドルの取得はできません。 - 許可したアプリは記憶されます。設定 → 接続済みアプリ でいつでも取り消せます。すべての端末でサインアウト やアカウントの削除で、すべてのアプリが取り消されます。
- 確認済み と表示されるのは、よく知られた一部のアプリだけです。それ以外のアプリでは、許可する前に戻り先のアドレスを確認してください。
https://bluesky.bot/api/mcpはサインインなしでも引き続き使えます。
Claude Code の場合:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcpCursor(.cursor/mcp.json)、VS Code(.vscode/mcp.json、"mcpServers" の代わりに "servers")、その他の多くのクライアントの場合:
{
"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)呼ばれ、どう終わったかだけです。何かを調べるツールは、ページと同じように、必要な公開サービスに入力を送ります。詳しくはプライバシーポリシーをご覧ください。