.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/bluesky-mcp-server</h1> <p><b>Search posts, profiles, feeds, threads, and trending topics on Bluesky via MCP. STDIO or Streamable HTTP.</b> <div>7 Tools • 1 Resource</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

Tools

Seven tools for read-only access to the public Bluesky/AT Protocol AppView — no authentication required:

bsky_search_posts

Full-text search across public Bluesky posts.

• Filters: author handle, language (BCP-47), hashtag, domain, date range (since/until), and sort order (top or latest)
• Returns posts with text, author, engagement counts (likes/reposts/replies/quotes), embeds, AT-URIs, and timestamps
• hitsTotal when available — total matching posts, not just the current page
• Pagination via opaque cursor; up to 100 results per call
• Embeds normalized into a flat union: images, external (link cards), record (quoted posts), video, unknown
• Moderation labels surfaced as-is — not filtered

bsky_get_profile

Fetch a Bluesky actor's public profile by handle or DID.

• Returns displayName, handle, DID, description, follower/following/post counts, avatar URL, moderation labels, and pinned post AT-URI
• The resolution step for handle↔DID — use before tools that require a DID or AT-URI when you only have a handle

bsky_get_author_feed

A user's recent posts ordered newest-first.

• Filter by post type: posts_with_replies, posts_no_replies, posts_with_media, or posts_and_author_threads
• Returns posts with full text, engagement counts, embeds, and AT-URIs for thread drilling
• Pagination via cursor

bsky_get_post_thread

Fetch the full conversation for a post by AT-URI.

• Returns the root post, parent chain (upward), and nested reply tree (downward)
• Configurable depth (reply tree depth, default 6) and parent_height (parent chain height, default 80)
• Truncated subtrees surface truncated: true; deleted posts surface as not_found
• AT-URIs come from bsky_search_posts or bsky_get_author_feed

bsky_get_follows

Fetch social graph edges for an account.

• direction: followers (who follows the actor) or following (who the actor follows)
• Returns paginated profiles with handle, DID, displayName, description, and follower count
• Includes the subject's profile summary at the top level

bsky_get_trending

Fetch real-time trending topics on Bluesky.

• Returns topics with display name, post count, category (politics, sports, pop-culture, etc.), status (hot/rising), and start time
• No cursor — returns the current snapshot up to limit
• Uses app.bsky.unspecced.getTrends — Bluesky may change this endpoint without notice

Resource

All resource data is also reachable via tools. Use bsky_get_profile for programmatic access or bsky://profile/{actor} to inject profile context directly.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

Bluesky-specific:

• No authentication required — all seven tools operate against api.bsky.app without credentials
• Single BlueskyService wrapping the AT Protocol public AppView with retry (3 attempts, 500ms base), 15s timeout, and a versioned User-Agent
• Embed normalization — raw nested AT Protocol embed objects flattened to a clean type-discriminated union
• Moderation labels surfaced verbatim — the agent and its human decide what to do
• AT Protocol identifier types (handle, DID, AT-URI) explained at first encounter in every tool description

Agent-friendly output:

• AT-URIs on every post and resource — chain bsky_search_posts → bsky_get_post_thread without extra steps
• Discriminated embed union (type: "images" | "external" | "record" | "video" | "unknown") — branch on data, not $type strings
• hitsTotal on search results — communicate result scale to users without extra round trips
• Truncation signals (truncated: true) on thread nodes — agents know where the tree ends and why

Getting started

Public Hosted Instance

Connect directly — no installation required:

{
  "mcpServers": {
    "bluesky-mcp-server": {
      "type": "streamable-http",
      "url": "https://bluesky.caseyjhand.com/mcp"
    }
  }
}

Self-hosted

Add the following to your MCP client configuration file. No API key required.

{
  "mcpServers": {
    "bluesky-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/bluesky-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "bluesky-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/bluesky-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "bluesky-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/bluesky-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).
• No API key or account required — all tools call api.bsky.app without credentials.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/bluesky-mcp-server.git

1. Navigate into the directory:

cd bluesky-mcp-server

1. Install dependencies:

bun install

1. Configure environment (optional):

cp .env.example .env
# edit .env to override any framework defaults

Configuration

This server requires no API keys. All framework configuration is optional.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t bluesky-mcp-server .
docker run --rm -p 3010:3010 bluesky-mcp-server

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

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the arrays in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.