API de herramientas y servidor MCP
Todas las herramientas de Bluesky.bot también se pueden usar gratis desde código y desde agentes de IA: como API REST y como herramientas de nuestro servidor MCP. Sin registro ni clave: llámalas. Cada respuesta enlaza con la página de la herramienta.
Endpoints
| Herramienta | API | Herramienta MCP |
|---|---|---|
| Buscador de DID | GET /api/v1/tools/did-finder?handle=… | find_did |
| Buscador de handle | GET /api/v1/tools/handle-finder?did=… | find_handle |
| Whois | GET /api/v1/tools/whois?actor=… | whois_lookup |
| Edad de una cuenta | GET /api/v1/tools/account-age?actor=… | check_account_age |
| Conversor de AT URI | GET /api/v1/tools/at-uri-converter?uri=… | convert_at_uri |
| Decodificador de TID | GET /api/v1/tools/tid-decoder?tid=… | decode_tid |
| Contador de caracteres | GET /api/v1/tools/character-counter?text=…&numbered=true | count_post_characters |
| Generador de facetas de texto enriquecido | GET /api/v1/tools/facet-builder?text=…&langs=en | build_post_facets |
| Verificador de handles con dominio propio | GET /api/v1/tools/custom-handle-checker?domain=…&expected=… | check_custom_handle |
| Verificador de disponibilidad de handles | GET /api/v1/tools/handle-availability?name=… | check_handle_availability |
| Historial PLC | GET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=false | plc_history |
| Analizador de starter packs | GET /api/v1/tools/starter-pack-analyser?q=… | analyse_starter_pack |
| Visor de publicaciones e hilos | GET /api/v1/tools/post-viewer?post=…&embed=false | view_bluesky_post |
| Inspector de feeds | GET /api/v1/tools/feed-inspector?feed=…&check=false | inspect_bluesky_feed |
La URL base es https://bluesky.bot/api/v1. Los parámetros y la respuesta
de cada herramienta están en la referencia de la API y en el
documento OpenAPI, /api/v1/openapi.json.
Una respuesta siempre tiene la misma forma: el slug de la herramienta, la
URL de su página y su result.
{
"tool": "character-counter",
"url": "https://bluesky.bot/tools/character-counter",
"result": { "graphemes": 16, "bytes": 19, "over": false, "parts": [] }
}Límites
- Gratis y anónimo: 60 llamadas por minuto y 2.000 al día por dirección IP. Una herramienta que envía varias peticiones por detrás cuenta como más de una llamada; la referencia de la API lo indica.
- Con un token de API: 10 veces ambos, contados por cuenta. Los
creadores con al menos un bot en Bluesky.bot crean uno en el panel, en
Ajustes → Acceso a la API y la CLI; un token de la
herramienta de línea de comandos también sirve. Envíalo en
Authorization: Bearer <token>. Un token dura 30 días; mantenlo fuera del código público. - Qué puede hacer un token del panel: llamar a las herramientas, nada
más. Tiene el alcance
tools: no puede gestionar tus bots, reservar ni liberar un handle, ni usar las rutas/api/v1/me/*de la CLI, que le responden401. - Por encima de un límite, la respuesta es
429con una cabeceraRetry-After, en segundos. - Un token desconocido, caducado o revocado recibe
401: quita la cabecera para llamar de forma anónima.
Los errores usan la forma habitual de la API,
{ "error": { "code", "message" } }, con bad_request (y el
parameter), unauthorized, not_found, rate_limited y
upstream_error (el servicio al que pregunta una herramienta no
respondió). Las respuestas llevan cabeceras CORS, para que una página web
pueda llamarlas, y una cabecera de caché: un cálculo puro, como el
contador, se guarda en caché para siempre.
Ejemplos
Con curl, que codifica el texto por ti:
curl -G "https://bluesky.bot/api/v1/tools/character-counter" \
--data-urlencode "text=Hello Bluesky! 👋"En JavaScript o TypeScript (Node.js 18 o posterior, Deno, Bun o un navegador):
// tools-api.ts: cuenta un post con la API gratuita de herramientas.
// Sin clave.
const url = new URL("https://bluesky.bot/api/v1/tools/character-counter");
url.searchParams.set("text", "Hello Bluesky! 👋");
// Un token de API creado en los ajustes del panel
// multiplica los límites por diez.
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}`);
// Convierte este archivo en un módulo ES, que el await de nivel superior necesita.
export {};En Python, con requests:
# tools_api.py: cuenta un post con la API gratuita de herramientas.
# Sin clave.
import os
import requests
# Un token de API creado en los ajustes del panel
# multiplica los límites por diez.
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']}")El texto viaja en la dirección de una petición GET, que los servidores
cortan hacia los 8 KB. Para un texto largo, usa el servidor MCP: envía la
entrada en el cuerpo de la petición.
Servidor MCP
El servidor MCP lista las mismas herramientas, con sus esquemas de entrada
y salida, para agentes de IA y editores: https://bluesky.bot/api/mcp
(Streamable HTTP, sin sesión). Todas las herramientas son de solo lectura.
Se aplican los mismos límites; un token en la cabecera Authorization los
amplía.
Conexión en un clic
¿Prefieres iniciar sesión a pegar un token? Añade
https://bluesky.bot/api/mcp/connect en su lugar. Tu app de IA abre una
página de Bluesky.bot: inicia sesión con tu cuenta de Bluesky (nunca te
pedimos la contraseña), comprueba el nombre de la app y la dirección a la
que te devuelve, y autoriza. La app recibe entonces su propio token y lo
renueva sola.
En Claude Code:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcp/connectEn Claude Desktop o en claude.ai, añade un conector personalizado con esa
URL y elige Conectar. En Cursor o VS Code, ponla como url de la
configuración de abajo e inicia sesión cuando el editor lo pida.
- La app recibe el ámbito
tools: las herramientas, con los límites más altos de tu cuenta si tienes un bot en Bluesky.bot. No puede publicar, gestionar tus bots ni reservar un handle. - Una app que autorizaste se recuerda. Revócala cuando quieras en Ajustes → Apps conectadas; Cerrar sesión en todas partes y borrar tu cuenta revocan todas las apps.
- Solo unas pocas apps conocidas aparecen como Verificada. Para las demás, comprueba la dirección a la que te devuelven antes de autorizar.
https://bluesky.bot/api/mcpsigue funcionando sin iniciar sesión.
En Claude Code:
claude mcp add --transport http bluesky-bot https://bluesky.bot/api/mcpEn Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, con
"servers" en lugar de "mcpServers") y la mayoría de los demás clientes:
{
"mcpServers": {
"bluesky-bot": { "url": "https://bluesky.bot/api/mcp" }
}
}En Claude Desktop o en claude.ai, añádelo como conector personalizado con
la misma URL. Con un token, añade una cabecera:
--header "Authorization: Bearer $BSBOT_TOKEN" en Claude Code, o
"headers": { "Authorization": "Bearer …" } junto a url en una
configuración JSON. Nunca subas a un repositorio un archivo de
configuración que contenga un token: guárdalo en una variable de entorno o
en los ajustes privados de tu cliente.
Qué se envía, qué se guarda
Lo que envías a una herramienta solo sirve para responder: nunca se guarda y se quita de nuestros informes de errores. Una llamada a la API lo lleva en su dirección: los registros de peticiones de nuestro servidor omiten esas direcciones, pero pasan por la red de Cloudflare que transporta el tráfico del sitio. MCP lo envía en el cuerpo de la petición, que ningún registro de peticiones guarda: puedes preferirlo para un texto sensible. Las estadísticas solo cuentan qué herramienta se llamó, desde dónde (una página, la API o MCP) y cómo terminó. Una herramienta que busca algo envía la entrada a los servicios públicos que necesita, como hace su página. Consulta la política de privacidad.