Bluesky MCP Server

@cyanheads/bluesky-mcp-server Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP. 11 Tools • 1 Profile Resource • 1 Guide

Public Hosted Server: https://bluesky.caseyjhand.com/mcp

Overview

Read Bluesky without an account: profiles, feed catalog searches, trending topics and the feeds behind them, custom and author feeds, threads, and quote posts. Paste a bsky.app link or @handle anywhere one is asked for, and add an optional app password to unlock full-text post search.

Tools

Resources

Use bsky_get_profile for programmatic access or bsky://profile/{actor} to inject profile context directly.

Agent guide

bluesky-guide covers topic research, account attribution, and reactions to a post, including identifier chains and coverage checks. It ships with plugin installs and is readable over MCP at skill://bluesky-guide/SKILL.md without credentials.

Capability reference

bsky_search_posts tool

• Bluesky refuses post search without a signed-in account, so this tool is registered only when BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD are set — without them it is absent from tools/list (see Post search)
• Searches run as that account through its PDS; the first search logs in, the session is reused and refreshed, and a rejected login is not retried. Failures surface as search_auth_failed (the login or its renewal was rejected), search_login_limited (the account's daily login limit is used up — the error names when searching resumes), or search_refused (Bluesky refused the search)
• Filters: author and mentioned account (handle or DID, also as @handle or a bsky.app profile URL — mentions matches rich-text mentions only), two-letter language code, hashtag (with or without #), linked domain (bare hostname, leading www. dropped) or exact url (in text links or link cards), since/until, and top/latest sort; up to 100 results per call via opaque cursor pagination
• since/until compare against each post's sort time — the earlier of createdAt and indexedAt — to the whole second, inclusive; a date alone is 00:00:00 UTC, so until: "2026-01-01" covers all of 2025-12-31
• Identifier, language, domain, URL, and date inputs are pattern-validated locally before the upstream call. A three-letter language code ("fil", "eng") is rejected, since Bluesky search ignores one and returns unfiltered results; the code is sent lowercased, and later subtags are accepted but ignored upstream (en-US filters as en)
• When Bluesky rejects a parameter, its own explanation is surfaced via the upstream_rejected_filter error reason instead of a bare status code; a cursor it can't decode fails as invalid_cursor, after one request
• hitsTotal is Bluesky's estimate, never an exact count: below 10,000 it is an upper bound on what paging returns (Bluesky counts before dropping posts it won't return), and exactly 10,000 — the cap — means "at least that many"; truncated/shown/cap are keyed on the returned cursor, which Bluesky omits once nothing more matches
• A page that would pass the 48,000-byte response budget on either surface is searched again at the limit that fits and returned whole — budgetCapped: true, with hitsTotal and the cursor from that one response
• Embeds normalize to a type-discriminated union (images, external, record, video, unknown); a quoted post carries its own attachments up to 3 nesting levels, with omittedEmbeds counting what went deeper and recordKind naming a quote that's deleted, blocked, detached, or not a post
• Video embeds retain nonempty alt, including on quoted posts and media attached alongside a quote; multiline alt renders as literal quoted text, like image alt
• Moderation labels are surfaced as-is, unfiltered

Post tools preserve optional rich-text facets separately from the original text: UTF-8 byte ranges (inclusive byteStart, exclusive byteEnd) and complete link URIs, mention DIDs, and tags. Unrecognized feature variants and additional upstream fields remain visible as literal metadata on both channels. Quoted posts retain their own facets within the existing embed-depth bound. Both response channels include this metadata in the response budget; bsky_get_post_quotes omits the queried target's facets together with its restated text.

bsky_get_feed tool

• Takes a feed generator AT-URI (at:// /app.bsky.feed.generator/ ) or its bsky.app page (https://bsky.app/profile/ /feed/ , with any trailing /, ?…, or #… ignored); a trend's feedUri works as-is, and Discover is at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.generator/whats-hot
• A handle owner costs one extra lookup (resolveHandle), a DID owner none; any other collection, such as a post AT-URI, is rejected before the upstream call
• A post the feed pinned to its top carries pinned: true; a repost carries repostedBy/repostedAt
• Up to 100 posts per call, paginated via cursor; truncation is disclosed on the cursor, since a feed can return fewer than limit with more behind it
• A page that would pass the 48,000-byte response budget is asked for again at the limit that fits and returned whole, marked budgetCapped: true; a ranked feed reranks on every request, so its posts and cursor still come from one response
• feed_not_found (no such feed or handle), feed_unavailable (the feed's generator did not answer — not retried, so a down feed fails fast), feed_requires_login (a personalized feed)
• Always unauthenticated, even when search credentials are set

bsky_get_profile tool

• Accepts a handle or DID, also as @handle or the account's bsky.app page (https://bsky.app/profile/ ); returns displayName, handle, DID, bio, pronouns, website, follower/following/post counts, avatar, moderation labels, and pinned post AT-URI
• website and pronouns are absent when the account set neither; optional links carries ordered profile buttons separately from website, with each record's URI/CID, complete destination URL, optional title/icon, and moderation labels (val, src?, cts?). An omitted array stays omitted and an explicit empty array stays empty; the profile resource returns the same fields
• Optional associated carries only supplied lists, feedgens, starterPacks, and labeler; zero counts, labeler: false, and an empty object stay distinct from absent metadata on both the tool and resource
• verification carries Bluesky's full verification state — verifiedStatus and trustedVerifierStatus (valid, invalid, or none, passed through verbatim) and every verification a trusted verifier issued, with its issuer, validity, date, and record AT-URI; absent when Bluesky sent none
• The bio renders as a markdown blockquote in content[], since it's account-authored text that can carry its own markdown structure
• actor_not_found when the handle doesn't resolve — resolve the handle with bsky_search_actors first
• The primary handle↔DID resolver — use before tools that require a DID or AT-URI when only a handle is known

bsky_get_author_feed tool

• Takes a handle or DID, also as @handle or the account's bsky.app page
• filter: posts_with_replies, posts_no_replies (default, excludes replies), and posts_and_author_threads include reposts; posts_with_media (the actor's own posts with images or video, no link cards) and posts_with_video return none
• include_pins: true adds the profile's pinned post, marked pinned: true, first on the first page — in addition to limit, and whether or not it matches filter
• Reposts carry repostedBy and repostedAt; author always names who actually wrote the post
• Under the filters that include reposts, limit counts them too, so a heavily-reposting account can return far fewer of its own posts than the limit suggests; originalPosts/reposts report the actual split whenever a repost is present
• Up to 100 posts per call, paginated via cursor; a page that would pass the 48,000-byte res