Skip to main content
Glama

bluesky-mcp-server

Get Bluesky Feed

bsky_get_feed
Read-onlyIdempotent

Read the posts a Bluesky feed generator serves, in the order the feed ranks them. Accepts the feed's AT-URI (at:///app.bsky.feed.generator/) or its bsky.app page (https://bsky.app/profile//feed/). Feeds come from the "feedUri" of each bsky_get_trending topic — the way to read what a trend is about — from bsky_search_feeds catalog results, from a quoted feed in a post (an embed with recordKind "generator"), or from a shared link; Discover is at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot. Returns posts with full text, engagement counts, embeds, and AT-URIs for drilling into threads via bsky_get_post_thread. A post the feed pinned to its top carries "pinned: true"; a repost carries "repostedBy". Personalized feeds, which Bluesky serves only to a signed-in account, cannot be read here. Supports cursor pagination.

Input Schema

NameRequiredDescriptionDefault
feedYesThe feed to read — its AT-URI, e.g. "at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot", or its bsky.app URL, e.g. "https://bsky.app/profile/bsky.app/feed/whats-hot"; a trailing "/", "?…", or "#…" on the URL is ignored. The owner may be a handle or a DID; a handle costs one extra lookup. A trend's "feedUri" works as-is.
limitNoMaximum number of posts to return. Default 25; values above 100 are clamped with a notice unless read-limit clamping is disabled. A feed may return fewer than the limit on a page that still has more after it — follow the cursor, not the count. A page that would pass the 48,000-byte response budget is asked for again with fewer posts and carries "budgetCapped: true"; its cursor continues after the posts it holds.
cursorNoOpaque pagination cursor from a previous response of the same feed. Omit for the first page.

Output Schema

NameRequiredDescriptionDefault
capNoThe limit applied to this page.
errorNoPresent when the call failed. Absent on success.
postsNoPosts the feed served, in the order it ranked them.
shownNoNumber of posts returned on this page.
cursorNoOpaque cursor for the next page. Absent when the feed has nothing further.
noticeNoGuidance when the feed returned nothing, or was cut.
truncatedNoTrue when the feed has more posts after this page (a cursor was returned).
budgetCappedNoTrue when a page of the requested limit would have passed this server's 48,000-byte response budget, so the feed was asked again for fewer posts and that page was returned whole. The cursor comes from that same response, so paging on from it continues where these posts end. Independent of "truncated", which still means only that a cursor was returned.
totalReturnedNoNumber of posts in this response page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of posts to return (1–100). Default 25. A feed may return fewer than the limit on a page that still has more after it — follow the cursor, not the count. A page that would pass the 48,000-byte response budget is asked for again with fewer posts and carries \"budgetCapped: true\"; its cursor continues after the posts it holds."New value: +"Maximum number of posts to return. Default 25; values above 100 are clamped with a notice unless read-limit clamping is disabled. A feed may return fewer than the limit on a page that still has more after it — follow the cursor, not the count. A page that would pass the 48,000-byte response budget is asked for again with fewer posts and carries \"budgetCapped: true\"; its cursor continues after the posts it holds."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +9007199254740991
    • changedOutput schema / properties / posts / items / properties / embed / description
      Previous value: -"Media or link embed attached to this post. type: \"images\" | \"external\" | \"record\" | \"video\" | \"unknown\". images: array of { url, alt } — also carries app.bsky.embed.gallery embeds. external: { uri, title, description }. record: { uri, cid, text?, authorHandle?, embeds?, media?, omittedEmbeds?, recordKind? } — embeds is the quoted post's own attachments; media is the image/video/link attached alongside the quote by the post doing the quoting, on a recordWithMedia embed. Both are embeds of these same shapes. omittedEmbeds counts attachments past the nesting this server follows — fetch the quote uri as its own post to read them. recordKind is absent for an ordinary quoted post and otherwise names what stood in for one: \"notFound\" | \"blocked\" | \"detached\" (the quote exists but cannot be read) or \"generator\" | \"list\" | \"starterPack\" | \"labeler\" | \"unknown\" (the quoted record is not a post). A \"generator\" quote is a feed: pass its uri to bsky_get_feed to read it. When recordKind is set, text and authorHandle are absent because that variant does not carry them. video: { playlist?, thumbnail?, presentation? }. unknown: { raw } — raw is the upstream $type this server has no mapping for."New value: +"Media or link embed attached to this post. type: \"images\" | \"external\" | \"record\" | \"video\" | \"unknown\". images: array of { url, alt } — also carries app.bsky.embed.gallery embeds. external: { uri, title, description }. record: { uri, cid, text?, facets?, authorHandle?, embeds?, media?, omittedEmbeds?, recordKind? } — facets retain UTF-8 byte ranges and link URI, mention DID, or tag features on the original text; embeds is the quoted post's own attachments; media is the image/video/link attached alongside the quote by the post doing the quoting, on a recordWithMedia embed. Both are embeds of these same shapes. omittedEmbeds counts attachments past the nesting this server follows — fetch the quote uri as its own post to read them. recordKind is absent for an ordinary quoted post and otherwise names what stood in for one: \"notFound\" | \"blocked\" | \"detached\" (the quote exists but cannot be read) or \"generator\" | \"list\" | \"starterPack\" | \"labeler\" | \"unknown\" (the quoted record is not a post). A \"generator\" quote is a feed: pass its uri to bsky_get_feed to read it. When recordKind is set, text and authorHandle are absent because that variant does not carry them. video: { playlist?, thumbnail?, presentation? }. unknown: { raw } — raw is the upstream $type this server has no mapping for."
    • addedOutput schema / properties / posts / items / properties / facets
      Added value: +{
      +  "description": "Rich-text facets on the unchanged text, with UTF-8 byte ranges and full link, mention, or tag values.",
      +  "items": {
      +    "additionalProperties": {},
      +    "description": "One rich-text annotation on the original post text.",
      +    "properties": {
      +      "features": {
      +        "description": "Features applied to this range, in upstream order.",
      +        "items": {
      +          "anyOf": [
      +            {
      +              "additionalProperties": {},
      +              "description": "Link destination.",
      +              "properties": {
      +                "$type": {
      +                  "const": "app.bsky.richtext.facet#link",
      +                  "description": "Link feature.",
      +                  "type": "string"
      +                },
      +                "uri": {
      +                  "description": "Complete destination URI, independent of abbreviated display text.",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "$type",
      +                "uri"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": {},
      +              "description": "Mention identity.",
      +              "properties": {
      +                "$type": {
      +                  "const": "app.bsky.richtext.facet#mention",
      +                  "description": "Mention feature.",
      +                  "type": "string"
      +                },
      +                "did": {
      +                  "description": "Mentioned account DID.",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "$type",
      +                "did"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": {},
      +              "description": "Tag value.",
      +              "properties": {
      +                "$type": {
      +                  "const": "app.bsky.richtext.facet#tag",
      +                  "description": "Tag feature.",
      +                  "type": "string"
      +                },
      +                "tag": {
      +                  "description": "Tag text without the leading hash.",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "$type",
      +                "tag"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": {},
      +              "description": "An open-union feature whose complete fields are retained as literal metadata.",
      +              "properties": {
      +                "$type": {
      +                  "description": "An upstream feature type other than the known link, mention, or tag types.",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "$type"
      +              ],
      +              "type": "object"
      +            }
      +          ],
      +          "description": "A known link, mention, or tag feature, or an upstream extension variant."
      +        },
      +        "type": "array"
      +      },
      +      "index": {
      +        "additionalProperties": {},
      +        "description": "UTF-8 byte range; these are not JavaScript string indices. Additional upstream fields are retained.",
      +        "properties": {
      +          "byteEnd": {
      +            "description": "Exclusive UTF-8 byte offset in the original text.",
      +            "maximum": 9007199254740991,
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "byteStart": {
      +            "description": "Inclusive UTF-8 byte offset in the original text.",
      +            "maximum": 9007199254740991,
      +            "minimum": 0,
      +            "type": "integer"
      +          }
      +        },
      +        "required": [
      +          "byteStart",
      +          "byteEnd"
      +        ],
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "index",
      +      "features"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed4 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum number of posts to return (1–100). Default 25. A feed may return fewer than the limit on a page that still has more after it — follow the cursor, not the count."New value: +"Maximum number of posts to return (1–100). Default 25. A feed may return fewer than the limit on a page that still has more after it — follow the cursor, not the count. A page that would pass the 48,000-byte response budget is asked for again with fewer posts and carries \"budgetCapped: true\"; its cursor continues after the posts it holds."
    • addedOutput schema / properties / budgetCapped
      Added value: +{
      +  "description": "True when a page of the requested limit would have passed this server's 48,000-byte response budget, so the feed was asked again for fewer posts and that page was returned whole. The cursor comes from that same response, so paging on from it continues where these posts end. Independent of \"truncated\", which still means only that a cursor was returned.",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the feed returned nothing."New value: +"Guidance when the feed returned nothing, or was cut."
    • addedOutput schema / properties / posts / items / properties / author / properties / verification
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Bluesky verification of the author — what tells a verified account from a look-alike handle. Absent when Bluesky sent none. Who issued it is on bsky_get_profile.",
      +  "properties": {
      +    "trustedVerifierStatus": {
      +      "description": "Whether the author is itself a trusted verifier — same values as verifiedStatus.",
      +      "type": "string"
      +    },
      +    "verifiedStatus": {
      +      "description": "Whether a trusted verifier verified the author: \"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"
      +}
  3. Changed3 schema fields changed
    • changedInput schema / properties / feed / description
      Previous value: -"The feed to read — its AT-URI, e.g. \"at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot\", or its bsky.app URL, e.g. \"https://bsky.app/profile/bsky.app/feed/whats-hot\". The owner may be a handle or a DID; a handle costs one extra lookup. A trend's \"feedUri\" works as-is."New value: +"The feed to read — its AT-URI, e.g. \"at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot\", or its bsky.app URL, e.g. \"https://bsky.app/profile/bsky.app/feed/whats-hot\"; a trailing \"/\", \"?…\", or \"#…\" on the URL is ignored. The owner may be a handle or a DID; a handle costs one extra lookup. A trend's \"feedUri\" works as-is."
    • changedInput schema / properties / feed / pattern
      Previous value: -"^(?:at:\\/\\/((?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])\\/app\\.bsky\\.feed\\.generator\\/([a-zA-Z0-9._~:-]{1,512})|https:\\/\\/bsky\\.app\\/profile\\/((?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])\\/feed\\/([a-zA-Z0-9._~:-]{1,512}))$"New value: +"^(?:at:\\/\\/(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])\\/app\\.bsky\\.feed\\.generator\\/[a-zA-Z0-9._~:-]{1,512}|https:\\/\\/bsky\\.app\\/profile\\/(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.)+[a-zA-Z](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?|did:[a-z]+:[a-zA-Z0-9._:%-]*[a-zA-Z0-9._-])\\/feed\\/[a-zA-Z0-9._~:-]{1,512}\\/?(?:[?#].*)?)$"
    • changedOutput schema / properties / posts / items / properties / quoteCount / description
      Previous value: -"Number of quote posts."New value: +"Number of quote posts Bluesky counts — read them with bsky_get_post_quotes. An upper bound on what that returns, since the counter keeps quotes that have left the index."
  4. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/openWorld/idempotent, and the description still adds real behavioral context: pinned posts carry "pinned: true", reposts carry "repostedBy", pages over the 48,000-byte budget are refetched with "budgetCapped: true", limits above 100 are clamped with a notice, and a short page may still have more. None of that is derivable from the annotations or schema.

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?

Purpose and input format lead, with behavioral caveats trailing. The middle sentence listing four feed sources is long and comma-chained, but every clause carries actionable routing information; nothing is padding.

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

Completeness5/5

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

With an output schema present and full parameter documentation, the description still covers the pagination contract, clamping, budget capping, and the signed-in-only limitation — everything an agent needs to call this correctly on the first attempt.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by noting that a handle costs an extra lookup versus a DID, that trailing '/', '?…', '#…' on a URL is ignored, and that callers should follow the cursor rather than the returned count.

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: 'Read the posts a Bluesky feed generator serves, in the order the feed ranks them.' The 'feed generator' framing cleanly separates it from bsky_get_author_feed and bsky_search_feeds, and the ordering behavior is stated up front.

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?

Enumerates concrete sources for the feed argument — a trend's "feedUri" from bsky_get_trending, bsky_search_feeds catalog results, a quoted generator embed, or a shared link — and names an explicit exclusion: personalized feeds 'cannot be read here.' That is when-to-use, where-the-input-comes-from, and when-not all in one place.

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.