BL
Developer Tools

Bluesky MCP Server for Automated AT Protocol Interactions

Automate Bluesky interactions with an MCP server for AT Protocol: posting, liking, reposting, timeline and profile management.

View on GitHub
Quick Install
npx -y @semioz/bluesky-mcp

Overview

The Bluesky MCP Server is a small HTTP server that exposes a set of programmatic “tools” for automating interactions with Bluesky (AT Protocol) instances. It implements a Model Context Protocol (MCP) friendly interface so LLM-driven agents, bots, or automation pipelines can call actions such as posting, liking, reposting, reading timelines, and managing profiles without dealing directly with the low-level AT Protocol details.

This server is useful when you want a thin abstraction between an AI or application and Bluesky: the MCP server translates simple tool calls into authenticated AT Protocol requests, handles session persistence and media uploads, and normalizes responses back to the caller. It’s intended for developers who want to integrate automated posting, feed processing, or account management as part of a larger toolchain.

Features

  • Programmatic posting (text and media uploads)
  • Like / unlike and repost / unrepost actions
  • Timeline read: home / feed / author timelines
  • Profile read and update (display name, description, avatar)
  • Follow and unfollow operations
  • Media upload support with automatic attachment handling
  • Simple HTTP endpoints designed for MCP/LLM tool invocation
  • Configurable AT Protocol instance and authentication via environment variables
  • Lightweight, self-hostable — runs locally or in a container

Installation / Configuration

Prerequisites:

  • Node 18+ (or Docker)
  • A Bluesky session token / credentials for the account you’ll automate

Clone and run locally:

git clone https://github.com/semioz/bluesky-mcp.git
cd bluesky-mcp
npm install
# create .env (see example below)
npm start

Example .env:

MCP_PORT=8080
AT_HOST=https://bsky.social        # AT Protocol service host
SESSION_TOKEN=your_bluesky_token   # session cookie or token used by this server
MAX_UPLOAD_SIZE=25mb
LOG_LEVEL=info

Run with Docker:

docker build -t bluesky-mcp .
docker run -d --name bluesky-mcp \
  -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e AT_HOST=https://bsky.social \
  -e SESSION_TOKEN=your_bluesky_token \
  bluesky-mcp

Notes on authentication:

  • Provide a session token (or session cookie) for the Bluesky account you control. Keep this secret and rotate when necessary.
  • The server uses the configured AT_HOST to determine API endpoints; switch to another AT instance by changing AT_HOST.

Available Tools

The server exposes REST endpoints intended to be used as MCP tools. Below is a condensed list of available operations and expected parameters.

Tool/EndpointMethodRequest Body (JSON)Description
/tools/postPOST{ text, replyTo?, attachments? }Create a post with optional media and reply-to
/tools/deletePostPOST{ postUri }Delete a previously created post
/tools/likePOST{ subjectUri }Like a post
/tools/unlikePOST{ subjectUri }Remove a like
/tools/repostPOST{ subjectUri }Repost (share) a post
/tools/unrepostPOST{ subjectUri }Remove a repost
/tools/timelineGETquery: { type=homefeed
/tools/profileGET/POSTGET -> { handle } POST -> { displayName?, description?, avatar? }Read or update profile
/tools/followPOST{ didOrHandle }Follow a user
/tools/unfollowPOST{ didOrHandle }Unfollow a user
/tools/uploadPOST (multipart)file uploadUpload media and return attachment metadata

Example tool call (cURL — create a post):

curl -X POST "http://localhost:8080/tools/post" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from MCP server!", "attachments": []}'

Use Cases

  • Automated posting agent: schedule or generate content using an LLM, then call /tools/post to publish it on Bluesky.
    • Example: a daily summary generator produces text, attachments uploaded via /tools/upload, and then /tools/post publishes it.
  • Feed summarization: fetch the home timeline via /tools/timeline, summarize recent posts with an LLM, and optionally reply or repost the summary.
    • Example sequence: GET /tools/timeline?type=home&limit=50 → summarize → POST /tools/post (replyTo: summarized post).
  • Moderation or content curation bot: follow or unfollow accounts, like posts that match rules, or clean up old posts by calling /tools/deletePost.
  • Cross-posting bridge: import content from another platform and publish to Bluesky through /tools/upload and /tools/post.
  • Profile automation: adjust profile descriptions, update avatars, or manage bio links programmatically for brand accounts.

Security & Operational Notes

  • Keep session tokens private. Run the server behind firewall or accessible only to trusted tools.
  • Respect rate limits of the AT Protocol instance. Implement exponential backoff on failures.
  • Consider running in a separate service account to limit blast radius (don’t use personal high-privilege accounts).
  • Log useful actions but avoid logging raw session tokens or sensitive content.

Available Resources

  • Source code and issues: https://github.com/semioz/bluesky-mcp
  • Typical integration pattern: call HTTP endpoints from your LLM orchestrator (e.g., a plugin agent implementing MCP) and treat endpoints as deterministic tools that return structured JSON responses.

This server is designed to be a developer-friendly bridge between higher-level automation and the AT Protocol, simplifying common workflows like posting, liking, timeline ingestion, and profile management.

Tags:developer-tools