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
| Tool | API | MCP tool |
|---|---|---|
| DID finder | GET /api/v1/tools/did-finder?handle=… | find_did |
| Handle finder | GET /api/v1/tools/handle-finder?did=… | find_handle |
| Whois | GET /api/v1/tools/whois?actor=… | whois_lookup |
| Account age | GET /api/v1/tools/account-age?actor=… | check_account_age |
| AT-URI converter | GET /api/v1/tools/at-uri-converter?uri=… | convert_at_uri |
| TID decoder | GET /api/v1/tools/tid-decoder?tid=… | decode_tid |
| Character counter | GET /api/v1/tools/character-counter?text=…&numbered=true | count_post_characters |
| Rich text facet builder | GET /api/v1/tools/facet-builder?text=…&langs=en | build_post_facets |
| Custom domain handle checker | GET /api/v1/tools/custom-handle-checker?domain=…&expected=… | check_custom_handle |
| Handle availability checker | GET /api/v1/tools/handle-availability?name=… | check_handle_availability |
| PLC history | GET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=false | plc_history |
| Starter pack analyser | GET /api/v1/tools/starter-pack-analyser?q=… | analyse_starter_pack |
| Post and thread viewer | GET /api/v1/tools/post-viewer?post=…&embed=false | view_bluesky_post |
| Feed inspector | GET /api/v1/tools/feed-inspector?feed=…&check=false | inspect_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.
{
"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
toolsscope: it cannot manage your bots, claim or release a handle, or use the CLI's/api/v1/me/*routes, which answer401to it. - Over a limit, the answer is
429with aRetry-Afterheader, 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:
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: 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: 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']}")The text travels in the address of a GET request, which servers cut at
about 8 KB. For a long text, use the MCP server: it sends the input in the
body of the request.
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:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connectIn 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
toolsscope: 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/mcpkeeps working without signing in.
In Claude Code:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcpIn Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, with "servers"
instead of "mcpServers") and most other clients:
{
"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.