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

HerramientaAPIHerramienta MCP
Buscador de DIDGET /api/v1/tools/did-finder?handle=…find_did
Buscador de handleGET /api/v1/tools/handle-finder?did=…find_handle
WhoisGET /api/v1/tools/whois?actor=…whois_lookup
Edad de una cuentaGET /api/v1/tools/account-age?actor=…check_account_age
Conversor de AT URIGET /api/v1/tools/at-uri-converter?uri=…convert_at_uri
Decodificador de TIDGET /api/v1/tools/tid-decoder?tid=…decode_tid
Contador de caracteresGET /api/v1/tools/character-counter?text=…&numbered=truecount_post_characters
Generador de facetas de texto enriquecidoGET /api/v1/tools/facet-builder?text=…&langs=enbuild_post_facets
Verificador de handles con dominio propioGET /api/v1/tools/custom-handle-checker?domain=…&expected=…check_custom_handle
Verificador de disponibilidad de handlesGET /api/v1/tools/handle-availability?name=…check_handle_availability
Historial PLCGET /api/v1/tools/plc-history?q=…&limit=50&page=1&include_raw=falseplc_history
Analizador de starter packsGET /api/v1/tools/starter-pack-analyser?q=…analyse_starter_pack
Visor de publicaciones e hilosGET /api/v1/tools/post-viewer?post=…&embed=falseview_bluesky_post
Inspector de feedsGET /api/v1/tools/feed-inspector?feed=…&check=falseinspect_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.

json
{
  "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 responden 401.
  • Por encima de un límite, la respuesta es 429 con una cabecera Retry-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:

bash
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
// 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
# 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']}")

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:

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

En 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/mcp sigue funcionando sin iniciar sesión.

En Claude Code:

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

En Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json, con "servers" en lugar de "mcpServers") y la mayoría de los demás clientes:

json
{
  "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.