Skip to main content
Glama

bluesky-mcp-server

Search Bluesky Actors

bsky_search_actors
Read-onlyIdempotent

Find Bluesky accounts by name or handle fragment. Returns ranked profiles with handle, DID, displayName, bio, account creation timestamp, moderation labels with provenance, pronouns when the account set them, and Bluesky verification status — which tells a verified account from a look-alike handle. Follower, following, and post counts and the website are not on this view — bsky_get_profile returns them for one account. Use before bsky_get_profile or bsky_get_author_feed when you have a name but not a confirmed handle. Supports cursor-based pagination for browsing beyond the first page of results.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "bsky_search_actors"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of actors to return. Default 25; values above 100 are clamped with a notice unless read-limit clamping is disabled.
queryYesName or handle fragment to search for, e.g. "alice" or "nytimes.com". Must not be blank.
cursorNoOpaque pagination cursor from a previous response to the same query. Omit for the first page.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit applied to this page.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of actors returned on this page.
actorsNoMatching actor profiles, ranked by relevance.
cursorNoOpaque cursor for the next page — pass it back with the same query. Absent on the last page.
noticeNoGuidance when the result set is empty or constrained.
truncatedNoTrue when Bluesky returned a cursor for another page, whatever this page held — pages often hold fewer actors than limit and still continue.
totalReturnedNoNumber of actors in this response page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / actors / items / properties / createdAt
      Added value: +{
      +  "description": "ISO 8601 timestamp of account creation, when supplied.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / actors / items / properties / labels / items / properties / cts
      Added value: +{
      +  "description": "ISO 8601 timestamp when the label was applied.",
      +  "type": "string"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of actors to return (1–100). Default 25."New value: +"Maximum number of actors to return. Default 25; values above 100 are clamped with a notice unless read-limit clamping is disabled."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +9007199254740991
  3. Changed1 schema field changed
    • addedOutput schema / properties / actors / items / properties / verification
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Bluesky verification of this account — what tells it from a look-alike handle. Absent when Bluesky sent none. Who issued it is on bsky_get_profile.",
      +  "properties": {
      +    "trustedVerifierStatus": {
      +      "description": "Whether this account is itself a trusted verifier — same values as verifiedStatus.",
      +      "type": "string"
      +    },
      +    "verifiedStatus": {
      +      "description": "Whether a trusted verifier verified this account: \"valid\", \"invalid\" (verified once, no longer holds), or \"none\". Passed through as Bluesky sends it, so another value may appear.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "verifiedStatus",
      +    "trustedVerifierStatus"
      +  ],
      +  "type": "object"
      +}
  4. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_cursor`: Bluesky could not continue from the cursor the request carried — it answers a cursor it cannot decode with HTTP 400. Other values are possible when a failure originates below the handler."
    • addedOutput schema / properties / error / properties / data / properties / reason / examples
      Added value: +[
      +  "invalid_cursor"
      +]
  5. Changed4 schema fields changed
    • changedInput schema / properties / cursor / description
      Previous value: -"Opaque pagination cursor from a previous response. Note: the public Bluesky AppView restricts cursor-based search pagination for unauthenticated requests — passing a cursor may return a 403 error. Cursor pagination is reliable only for bsky_get_author_feed and bsky_get_follows."New value: +"Opaque pagination cursor from a previous response to the same query. Omit for the first page."
    • removedOutput schema / properties / actors / items / properties / followersCount
      Removed value: -{
      -  "description": "Number of followers.",
      -  "type": "number"
      -}
    • changedOutput schema / properties / cursor / description
      Previous value: -"Opaque cursor returned by the API. Unreliable for unauthenticated search requests on the public AppView — passing it on a subsequent call may return a 403 error."New value: +"Opaque cursor for the next page — pass it back with the same query. Absent on the last page."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when more actors match than were returned on this page."New value: +"True when Bluesky returned a cursor for another page, whatever this page held — pages often hold fewer actors than limit and still continue."
  6. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "actors",
      +      "totalReturned"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode.",
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "actors",
      -  "totalReturned"
      -]
  7. Changed1 schema field changed
    • addedOutput schema / properties / actors / items / properties / pronouns
      Added value: +{
      +  "description": "Free-form pronouns the account set, e.g. \"they/he\". Absent when it set none. Account-authored text bounded only by length, not a fixed vocabulary — read it as written rather than parsing it.",
      +  "type": "string"
      +}
  8. Changed3 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Name or handle fragment to search for, e.g. \"alice\" or \"nytimes.com\"."New value: +"Name or handle fragment to search for, e.g. \"alice\" or \"nytimes.com\". Must not be blank."
    • addedInput schema / properties / query / minLength
      Added value: +1
    • addedInput schema / properties / query / pattern
      Added value: +"\\S"
  9. Changed3 schema fields changed
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The limit applied to this page.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of actors returned on this page.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when more actors match than were returned on this page.",
      +  "type": "boolean"
      +}
  10. First observed

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, and openWorld, but the description adds genuinely new behavior: what fields come back, that moderation labels carry provenance, that verification status disambiguates look-alike handles, and that results are cursor-paginated. It does not cover rate limits, auth expectations, or empty-result behavior, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and usage rule before the field inventory, and every sentence carries information. Slightly dense in the return-field enumeration, which overlaps with the output schema, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still adds value by stating what is deliberately absent (follower/following/post counts, website) and where to get it, plus pagination support. Complete for an agent to call it correctly; only error/empty-result handling is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so query, limit (including clamping above 100), and cursor are already fully documented in the schema. The description only echoes pagination existence without adding format or syntax detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Find Bluesky accounts by name or handle fragment.' It immediately distinguishes itself from the sibling lookups by scope (name/handle search vs. known-account retrieval), so an agent can choose it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit selection rule: 'Use before bsky_get_profile or bsky_get_author_feed when you have a name but not a confirmed handle,' and names bsky_get_profile as the alternative when follower counts or website are needed. Both the when-to-use and the alternative path are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.