Tools API and MCP server

Every Bluesky.bot tool is also free to use from code and from AI agents: as a REST API, and as a tool of our MCP server. No sign-up, no key: call it. Each answer links back to the tool's page.

Endpoints

ToolAPIMCP tool
DID finderGET /api/v1/tools/did-finder?handle=…find_did
Handle finderGET /api/v1/tools/handle-finder?did=…find_handle
WhoisGET /api/v1/tools/whois?actor=…whois_lookup
Account ageGET /api/v1/tools/account-age?actor=…check_account_age
AT-URI converterGET /api/v1/tools/at-uri-converter?uri=…convert_at_uri
TID decoderGET /api/v1/tools/tid-decoder?tid=…decode_tid
Character counterGET /api/v1/tools/character-counter?text=…&numbered=truecount_post_characters
Rich text facet builderGET /api/v1/tools/facet-builder?text=…&langs=enbuild_post_facets
Custom domain handle checkerGET /api/v1/tools/custom-handle-checker?domain=…&expected=…check_custom_handle
Handle availability checkerGET /api/v1/tools/handle-availability?name=…check_handle_availability
PLC historyGET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=falseplc_history
Starter pack analyserGET /api/v1/tools/starter-pack-analyser?q=…analyse_starter_pack
Post and thread viewerGET /api/v1/tools/post-viewer?post=…&embed=falseview_bluesky_post
Feed inspectorGET /api/v1/tools/feed-inspector?feed=…&check=falseinspect_bluesky_feed

The base URL is https://bluesky.bot/api/v1. Each tool's parameters and answer are in the API reference and in the OpenAPI document, /api/v1/openapi.json.

An answer always has the same shape: the tool's slug, the URL of its page, and its result.

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

Limits

  • Free and anonymous: 60 calls a minute and 2,000 a day per IP address. A tool that sends several requests behind the scenes costs more than one call; the API reference says so.
  • With an API token: 10 times both, counted per account. Creators with at least one bot on Bluesky.bot make one in the dashboard, under Settings → API and CLI access; a token of the command-line tool works too. Send it as Authorization: Bearer <token>. A token lasts 30 days; keep it out of public code.
  • What a dashboard token can do: call the tools, nothing else. It has the tools scope: it cannot manage your bots, claim or release a handle, or use the CLI's /api/v1/me/* routes, which answer 401 to it.
  • Over a limit, the answer is 429 with a Retry-After header, in seconds.
  • An unknown, expired or revoked token gets 401: remove the header to call anonymously.

Errors use the API's usual shape, { "error": { "code", "message" } }, with bad_request (and the parameter), unauthorized, not_found, rate_limited and upstream_error (the service a tool asks did not answer). Answers carry CORS headers, so a web page can call them, and a cache header: a pure computation, like the counter, is cached for good.

Examples

With curl, which encodes the text for you:

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

In JavaScript or TypeScript (Node.js 18 or later, Deno, Bun or a browser):

tools-api.ts
// tools-api.ts: count a post with the free tools API. No key needed.
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");

// An API token from your dashboard settings raises the limits tenfold.
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}`);

// Makes this file an ES module, which top-level await needs.
export {};

In Python, with requests:

tools-api.py
# tools_api.py: count a post with the free tools API. No key needed.
import os

import requests

# An API token from your dashboard settings raises the limits tenfold.
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 server

The MCP server lists the same tools, with their input and output schemas, for AI agents and editors: https://bluesky.bot/api/mcp (Streamable HTTP, no session). Every tool is read-only. The same limits apply; a token in the Authorization header raises them.

Connect in one click

Rather sign in than paste a token? Add https://bluesky.bot/api/mcp/connect instead. Your AI app opens a Bluesky.bot page: sign in with your Bluesky account (we never ask for your password), check the app's name and the address it sends you back to, and approve. The app then gets a token of its own, and renews it by itself.

In Claude Code:

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

In Claude Desktop or on claude.ai, add a custom connector with that URL and pick Connect. In Cursor or VS Code, put it as the url of the configuration below, then sign in when the editor asks.

  • The app gets the tools scope: the tools, with your account's higher limits when you have a bot on Bluesky.bot. It cannot post, manage your bots or claim a handle.
  • An app you approved is remembered. Revoke it anytime under Settings → Connected apps; Sign out everywhere and deleting your account revoke every app.
  • Only a few well-known apps are marked Verified. For any other, check the address it sends you back to before you approve.
  • https://bluesky.bot/api/mcp keeps working without signing in.

In Claude Code:

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

In Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, with "servers" instead of "mcpServers") and most other clients:

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

In Claude Desktop or on claude.ai, add it as a custom connector with the same URL. With a token, add a header: --header "Authorization: Bearer $BSBOT_TOKEN" in Claude Code, or "headers": { "Authorization": "Bearer …" } next to url in a JSON configuration. Never commit a configuration file that holds a token: keep the token in an environment variable, or in your client's private settings.

What is sent, what is kept

What you send a tool is only used to answer: it is never stored, and it is removed from our error reports. An API call carries it in its address: our server's request logs skip these addresses, but they pass through the Cloudflare network that carries the site's traffic. MCP sends it in the body of the request, which no request log keeps: you may prefer it for sensitive text. Analytics only count which tool was called, from where (a page, the API or MCP) and how it ended. A tool that looks something up sends the input to the public services it needs, as its page does. See the privacy policy.