[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_127":128},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":79,"_80":-5,"_81":-5,"_82":-5,"_83":49,"_84":-5,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96,"_97":98},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","bluesky-mcp-server","@cyanheads/bluesky-mcp-server","displayName","bluesky mcp server","tagline","Search posts, profiles, feeds, threads, and trending topics on Bluesky.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://bluesky.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363414000,"updatedAt",1788329526000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fbluesky-mcp-server","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1787625755000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt",1787633266000,"githubRepoUrl","https://github.com/cyanheads/bluesky-mcp-server","githubRepoFullName","cyanheads/bluesky-mcp-server","releaseId","ext-cyanheads-bluesky-mcp-server","version","0.3.1","descriptionMarkdown","

@cyanheads/bluesky-mcp-server

Search posts, profiles, feeds, threads, and trending topics on Bluesky via MCP. STDIO or Streamable HTTP.\n

7 Tools • 1 Resource

\n\n

\n\n[![Version](https://img.shields.io/badge/Version-0.3.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/bluesky-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/bluesky-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/bluesky-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n

\n\n

\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/bluesky-mcp-server/releases/latest/download/bluesky-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=bluesky-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYmx1ZXNreS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22bluesky-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fbluesky-mcp-server%22%5D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n

\n\n

\n\n**Public Hosted Server:** [https://bluesky.caseyjhand.com/mcp](https://bluesky.caseyjhand.com/mcp)\n\n

\n\n---\n\n## Tools\n\nSeven tools for read-only access to the public Bluesky/AT Protocol AppView — no authentication required:\n\n| Tool | Description |\n|:-----|:------------|\n| `bsky_search_posts` | Full-text search across public Bluesky posts, with author, language, tag, date, and sort filters |\n| `bsky_get_profile` | Fetch a Bluesky actor's public profile by handle or DID — the handle↔DID resolver |\n| `bsky_get_author_feed` | A user's recent posts ordered newest-first, filterable by post type |\n| `bsky_get_post_thread` | Fetch the conversation for a post by AT-URI — parent chain upward and reply tree downward, with what Bluesky counted but did not return |\n| `bsky_search_actors` | Find Bluesky accounts by name or handle fragment |\n| `bsky_get_follows` | Paginated social graph edges — who a user follows or who follows them |\n| `bsky_get_trending` | Real-time trending topics on Bluesky with post count, category, status, and the accounts driving each topic |\n\n### `bsky_search_posts`\n\nFull-text search across public Bluesky posts.\n\n- Filters: author handle, language (BCP-47), hashtag, date range (`since`/`until`), and sort order (`top` or `latest`)\n- Identifier, language, and date inputs are pattern-validated before the upstream call — a malformed handle, DID, AT-URI, language tag, or date fails locally with the expected shape instead of a generic upstream 400. Language is checked for BCP-47 *shape* only, matching Bluesky itself: a well-formed tag naming no indexed language returns unfiltered results rather than an error, and the field description says so\n- When Bluesky rejects a parameter anyway, its own explanation is surfaced as the error reason and recovery hint instead of a bare `Status: 400`\n- Returns posts with text, author, engagement counts (likes/reposts/replies/quotes), embeds, AT-URIs, and timestamps\n- `hitsTotal` when available, reported as the bound it is — Bluesky caps the count at 10,000, so exactly 10,000 means \"at least 10,000\" and both the field description and the rendered header say so\n- Truncation is disclosed (`truncated`, `shown`, `cap`, and guidance) in both `structuredContent` and the `content[]` trailer when more posts match than came back. A returned cursor alone does not trigger it — Bluesky sends one on every non-empty response, exhausted or not, so `hitsTotal` is what settles whether the page was cut short\n- Pagination via opaque cursor; up to 100 results per call\n- Embeds normalized into a flat union: `images` (also covers `app.bsky.embed.gallery`), `external` (link cards), `record` (quoted posts), `video`, `unknown`\n- A quoted post carries its own attachments under `embeds`, so a quote of an image post is not reduced to a line of text, alongside `media` for anything the quoting post attached beside the quote. The rendered output names which post each block belongs to, since the two belong to different accounts\n- Quote nesting is followed three levels down, which is deeper than the AppView has been seen to hydrate. A quote at that bound reports the attachments it did not carry through as `omittedEmbeds` and says so in the rendered text, so it never reads as a quote that had none\n- A quote that cannot be read — deleted, blocked, detached — or that points at a feed generator, list, starter pack, or labeler rather than a post carries `recordKind` naming the case, instead of arriving as an empty quote\n- Moderation labels surfaced as-is — not filtered\n\n---\n\n### `bsky_get_profile`\n\nFetch a Bluesky actor's public profile by handle or DID.\n\n- Returns displayName, handle, DID, description, pronouns, website, follower/following/post counts, avatar URL, moderation labels, and pinned post AT-URI\n- `website` is the one link a profile carries in a field of its own rather than inside the bio; both it and `pronouns` are absent for accounts that set neither\n- The bio is rendered as a blockquote — it is text the account holder wrote, and can carry markdown of its own. The display name and pronouns render inside lines the server writes, with their line breaks folded to spaces, so neither can open a heading of its own\n- The resolution step for handle↔DID — use before tools that require a DID or AT-URI when you only have a handle\n\n---\n\n### `bsky_get_author_feed`\n\nA user's recent feed ordered newest-first — their own posts and their reposts.\n\n- Filter by post type: `posts_with_replies`, `posts_no_replies` (excludes replies), `posts_with_media`, or `posts_and_author_threads`. None of them exclude reposts — the AppView has no repost filter\n- Reposts carry `repostedBy` and `repostedAt`; `author` always names whoever wrote the post\n- Because `limit` counts reposts too, a page from an account that reposts heavily holds far fewer of that account's own posts than the limit suggests — 30 items from one such account came back as 10 originals and 20 reposts. The response reports `originalPosts` and `reposts` whenever a repost is present, so the yield is stated rather than reconstructed by counting\n- Returns posts with full text, engagement counts, embeds, and AT-URIs for thread drilling\n- Pagination via cursor\n\n---\n\n### `bsky_get_post_thread`\n\nFetch the conversation for a post by AT-URI.\n\n- Returns the root post, parent chain (upward), and nested reply tree (downward)\n- Configurable `depth` (reply tree depth, default 6, max 10 — Bluesky returns no more than 10 levels however deep the request) and `parent_height` (parent chain height, default 80, max 100)\n- Bluesky holds replies back past a per-post limit and exposes no way to page the rest, so a thread with thousands of replies commonly comes back with a few hundred. Any node returning fewer replies than its own `replyCount` carries `truncated: true` with `unreturnedReplies` and a `truncationReason`: `\"depth\"` (the tree ends there — fetch that node's AT-URI as its own thread to continue) or `\"unavailable\"` (no request closes the gap). The response totals the difference for the whole thread\n- Read those totals as an upper bound on what is missing, not a count of readable replies — Bluesky's reply counter keeps including replies that have left the index, so a difference of one or two often means nothing is left to fetch\n- The parent chain is disclosed the same way. Bluesky stops the chain at `parent_height` and gives no signal that it did, so the topmost post returned would otherwise be indistinguishable from the start of the conversation. When it is not, that node carries `parentChainTruncated: true` and the response names its AT-URI — unlike the reply shortfall this one is fully recoverable, since `parent_height` is honored level for level and fetching that node as its own thread walks further up\n- Reply depth rides the author heading (`### ↳2 Name (@handle)` — two levels below the top-level reply it descends from) rather than a left margin, so a nested reply stays readable markdown. Indenting instead would push every line below the second level past four spaces, which renders the whole nested half of a thread as a code block. The number is stated rather than repeated as a glyph, since a reply can sit nine levels down and a run of nine arrows has to be counted to be read\n- Surfaces the author's reply gate when one is set: who may reply, and the AT-URIs of replies the author hid\n- Deleted posts surface as `notFound: true` and posts hidden by a block as `blocked: true`; both keep the AT-URI Bluesky reported\n- AT-URIs come from `bsky_search_posts` or `bsky_get_author_feed`\n\n---\n\n### `bsky_get_follows`\n\nFetch social graph edges for an account.\n\n- `direction`: `followers` (who follows the actor) or `following` (who the actor follows)\n- Returns paginated profiles with handle, DID, displayName, description, pronouns when the account set them, and follower count\n- Includes the subject's profile summary at the top level, pronouns included\n- No `website` — the view these two endpoints return does not carry it; resolve the account with `bsky_get_profile` when it matters\n\n---\n\n### `bsky_get_trending`\n\nFetch real-time trending topics on Bluesky.\n\n- Returns topics with display name, post count, category (politics, sports, pop-culture, etc.), status (hot/rising), and start time\n- Each topic carries the representative accounts driving it, so \"who is talking about this\" costs no follow-up search\n- No cursor — returns the current snapshot up to `limit`\n- Uses `app.bsky.unspecced.getTrends` — Bluesky may change this endpoint without notice\n\n## Resource\n\n| Type | Name | Description |\n|:-----|:-----|:------------|\n| Resource | `bsky://profile/{actor}` | A Bluesky actor's public profile, addressable by handle or DID |\n\nAll resource data is also reachable via tools. Use `bsky_get_profile` for programmatic access or `bsky://profile/{actor}` to inject profile context directly.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nBluesky-specific:\n\n- No authentication required — all seven tools operate against `api.bsky.app` without credentials\n- Single `BlueskyService` wrapping the AT Protocol public AppView with retry (3 attempts, 500ms base), 15s timeout, and a versioned `User-Agent`\n- Embed normalization — raw nested AT Protocol embed objects flattened to a clean `type`-discriminated union\n- Moderation labels surfaced verbatim — the agent and its human decide what to do\n- AT Protocol identifier types (handle, DID, AT-URI) explained at first encounter in every tool description\n\nAgent-friendly output:\n\n- AT-URIs on every post and resource — chain `bsky_search_posts` → `bsky_get_post_thread` without extra steps\n- Discriminated embed union (`type: \"images\" | \"external\" | \"record\" | \"video\" | \"unknown\"`) — branch on data, not `$type` strings; an unmapped lexicon type arrives as `unknown` with its raw `$type` rather than vanishing\n- Unreadable and non-post quotes discriminated by `recordKind` — an agent can tell a deleted or blocked quote from one whose text was simply not returned\n- Attachments a quote nested past the mapped depth would have carried are counted in `omittedEmbeds` rather than dropped, so the bound on embed recursion is visible in both channels\n- Both response channels carry the same fields. A post and its embed normalize to exactly what the rendered `content[]` emits — image and video URLs, alt text, link-card title and description, the AT-URI and CID of a quoted post, the author's handle, DID, display name, and avatar, and each moderation label with the labeler that applied it and when — so a client reading `structuredContent` and one reading the rendered text see the same post. Pixel dimensions and a link card's preview thumbnail are left upstream rather than reaching one channel alone, and account-level detail is a `bsky_get_profile` lookup away\n- Text Bluesky users wrote — post bodies, quoted-post bodies, profile bios, pronouns, image alt text, and link-card titles and descriptions — is rendered as a markdown blockquote, every line prefixed with `>` and blank lines kept as a bare `>`. A post carrying its own `###` heading, `---` rule, or fenced code block stays inside the quote instead of merging with the server's own section structure, so third-party content never reaches a model in the same channel as the server's labels. Values that render inside a line rather than as a block — display names, pronouns, topic names, moderation label values — have their line breaks folded to spaces for the same reason. `structuredContent` carries every string unchanged\n- Nothing in the rendered output indents past three spaces. Four leading spaces open a markdown code block, which would render that framing as literal characters instead of a quote — so nesting is carried by labels and headings, and both thread depth and embed depth are bounded by that budget rather than spending it\n- `hitsTotal` on search results, framed as a lower bound at Bluesky's 10,000 cap — communicate result scale without reporting a ceiling as a measurement\n- Truncation signals on thread nodes (`truncated`, `unreturnedReplies`, `truncationReason`, `parentChainTruncated`) plus a thread-wide total, stated as a bound rather than a cause — agents can tell how much of a conversation may be missing at either end, which part another request can still reach, and how much of the gap the thread author explains\n\n## Getting started\n\n### Public Hosted Instance\n\nConnect directly — no installation required:\n\n```json\n{\n \"mcpServers\": {\n \"bluesky-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://bluesky.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-hosted\n\nAdd the following to your MCP client configuration file. No API key required.\n\n```json\n{\n \"mcpServers\": {\n \"bluesky-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/bluesky-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"bluesky-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/bluesky-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"bluesky-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/bluesky-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API key or account required — all tools call `api.bsky.app` without credentials.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/bluesky-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd bluesky-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment (optional):**\n\n```sh\ncp .env.example .env\n# edit .env to override any framework defaults\n```\n\n## Configuration\n\nThis server requires no API keys. All framework configuration is optional.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |\n| `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`. The schema default `auto` resolves to stateful. | `stateless` |\n| `MCP_HTTP_PORT` | Port for HTTP server | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth` | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424) | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only) | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) | `false` |\n\nSee [`.env.example`](https://github.com/cyanheads/bluesky-mcp-server/blob/main/.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t bluesky-mcp-server .\ndocker run --rm -p 3010:3010 bluesky-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/bluesky-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools, resource, and inits service. |\n| `src/services/bluesky` | AT Protocol AppView HTTP client with retry, timeout, and `User-Agent`. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — seven read-only Bluesky tools. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`) — `bsky://profile/{actor}`. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](https://github.com/cyanheads/bluesky-mcp-server/blob/main/CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the arrays in `src/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](https://github.com/cyanheads/bluesky-mcp-server/blob/main/LICENSE) for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_107":108,"_109":110,"_111":112,"_113":114,"_115":116,"_117":118},"requiredSecrets",[],"tags",[101,102,103,104,19,105,106],"assets",[],"stats",{"_99":86,"_100":86},"ratingAvg","reviewCount","ai-agents","ai-tools","atproto","bluesky","social","typescript","topics",[101,102,103,104,19,124,125,126,105,106],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/bluesky-mcp-server","homepage","https://www.npmjs.com/package/@cyanheads/bluesky-mcp-server","packages",[119,120],{"_121":122,"_123":22,"_76":77},{"_121":122,"_123":22,"_76":77},"registryType","npm","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_129":130,"_131":132,"_133":134},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]