Bluesky MCP Server

What bluesky-mcp-server does

bluesky-mcp-server exposes Bluesky discovery and reading functions as MCP tools. It can resolve profiles by handle or DID, search accounts and public feed catalogs, read author and custom feeds, inspect conversations and quote posts, retrieve follow relationships, and report real-time trending topics. A profile resource is also available at bsky://profile/{actor}; the actor can be supplied as a handle or DID.

The server supports public, unauthenticated reading for most capabilities. Full-text post search is the exception: Bluesky requires a signed-in account for that operation, so the search tool is only registered when credentials are configured.

How it works

Connections can use either stdio or Streamable HTTP. A hosted endpoint is available at https://bluesky.caseyjhand.com/mcp, and the project also provides install links for Claude Desktop, Cursor, and VS Code.

Tools accept Bluesky-native identifiers such as handles, DIDs, AT-URIs, and bsky.app URLs where applicable. Feed results, post searches, and follow lists support cursor-based pagination. Feed generators can be selected directly by AT-URI or URL, while feed catalog search returns feed URIs that can then be passed to the feed reader.

Responses preserve useful Bluesky metadata, including moderation labels and optional rich-text facets. Post embeds are normalized by type, and quoted posts retain nested attachments up to a bounded depth. Responses are capped to a 48,000-byte budget when needed, with the result marked as budget-capped.

Setup and configuration

The package is available as @cyanheads/bluesky-mcp-server and can be installed through the linked MCP client setup flows or run with npx. The server can be used without a Bluesky account for profile, feed, thread, quote, actor, follow, catalog, and trend operations.

To enable bsky_search_posts, set both BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD. Searches authenticate as that account through its PDS. The session is reused and refreshed after login; rejected authentication is surfaced rather than repeatedly retried.

Tools and capabilities

• bsky_search_posts searches public posts with author, mention, language, hashtag, domain, URL, date, and sort filters.
• bsky_get_profile resolves a handle or DID to a public profile.
• bsky_get_feed reads Discover, trend feeds, or custom feed generators.
• bsky_get_author_feed returns a user’s recent posts with post-type filtering.
• bsky_get_post_thread retrieves parent posts and replies for a conversation.
• bsky_get_post_quotes lists quote posts by recency or like count.
• bsky_search_actors and bsky_search_feeds find accounts and feed generators.
• bsky_get_follows reads paginated follower or following edges.
• bsky_get_trending returns topics, summaries, counts, categories, driving accounts, and associated feeds.

Limitations and notes

Post-search results are subject to Bluesky’s behavior and limits. hitsTotal is an estimate rather than an exact count, and Bluesky may omit posts it counted. Search input is locally validated, while upstream filter rejections are returned with an explanation. Search failures can include authentication, login-limit, or upstream refusal errors.

Feeds may be unavailable, require login, or return fewer items than requested while more results remain behind the cursor. Ranked feeds can change between requests. Feed reading remains unauthenticated even when search credentials are present. A missing feed or unresolved handle is reported as an error rather than retried.

Moderation labels are returned as supplied by Bluesky. Deleted, blocked, detached, or otherwise unavailable quoted posts are identified in embed metadata when applicable.