# bluesky-mcp-server [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/cyanheads/bluesky-mcp-server  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1232  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bluesky-mcp-server

## Description
Search posts, profiles, feeds, threads, and trending topics on Bluesky.

## Tools
Capabilities this server exposes over MCP:

- **bsky_search_posts** — Full-text search across public Bluesky posts, with author, mention, language, tag, domain, URL, date, and sort filters — offered only when an app password is configured
- **bsky_get_profile** — Fetch a Bluesky actor's public profile by handle or DID — the handle↔DID resolver
- **bsky_get_feed** — Read a feed generator's posts — a trend's feed, Discover, or any custom feed — by AT-URI or bsky.app URL
- **bsky_get_author_feed** — A user's recent posts ordered newest-first, filterable by post type
- **bsky_get_post_thread** — Fetch the conversation for a post by AT-URI or bsky.app URL — parent chain upward and reply tree downward, with what Bluesky counted but did not return
- **bsky_get_post_quotes** — Read the quote posts behind a post's `quoteCount`, newest first or by like count — where much of the reaction to a post lives
- **bsky_search_actors** — Find Bluesky accounts by name or handle fragment
- **bsky_search_feeds** — Search public feed catalog names and descriptions, then read a returned feedUri with `bsky_get_feed
- **bsky_get_follows** — Paginated social graph edges — who a user follows or who follows them
- **bsky_get_trending** — Real-time trending topics on Bluesky with a story summary, post count, category, status, the accounts driving each topic, and the feed that collects its posts

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "bluesky-mcp-server": {
    "command": "bunx",
    "args": ["@cyanheads/bluesky-mcp-server@latest"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/bluesky-mcp-server/readme_