bluesky-mcp-server

v1.0.65

Published

19 days ago

Standalone Bluesky MCP Server — SENSE + ACT tools for the AT Protocol

0High
0Medium
0Low

🦋 Bluesky MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop (and other MCP clients) to read and post on Bluesky via the AT Protocol.

✨ Features

⚡ Built-in Reliability

Session Caching — Authenticated sessions are reused for 90 minutes to avoid login rate limits (30 logins/5min on Bluesky)
Rate Limiting — Token-bucket rate limiting across read, write, and session operation buckets
Auto-retry — Exponential backoff on HTTP 429 responses
Actionable Errors — Every error response includes a structured action field with exactly what to do next

🔍 SENSE Tools (Read) — 9 Tools

📰 bsky_get_timeline — Get the home timeline from followed accounts
🔔 bsky_get_notifications — Likes, reposts, follows, mentions, and replies
🔎 bsky_search_posts — Search by keyword, phrase, hashtag, or from:handle
🧵 bsky_get_post_thread — Fetch a thread with full parent context and replies
👤 bsky_get_profile — Get any user's profile by handle or DID
👥 bsky_get_followers — List followers of an account
🕵️ bsky_search_users — Find users by name, handle, or keyword
📡 bsky_get_feed — Get posts from any custom feed generator
📐 bsky_get_media_specs — Check supported formats, dimensions, and size limits before generating media

✍️ ACT Tools (Write) — 6 Tools

✏️ bsky_create_post — Create posts with text, link preview cards, images (JPEG/PNG), or video (MP4)
💬 bsky_reply — Reply to any post with optional link preview card
❤️ bsky_like — Like a post by URI + CID
🔁 bsky_repost — Repost a post by URI + CID
➕ bsky_follow — Follow a user by DID
🗑️ bsky_delete_post — Delete a post by URI

🚀 Quick Start

Prerequisites

Node.js 18 or higher
A Bluesky account with an App Password — generate one at bsky.app/settings/app-passwords
Claude Desktop (or any MCP-compatible client)

Installation

Option 1: npx (Zero Install) ⚡

Run directly without installing anything:

BLUESKY_HANDLE=you.bsky.social BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx npx bluesky-mcp-server

Claude Desktop Configuration for npx:

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bluesky": {
      "command": "npx",
      "args": ["bluesky-mcp-server"],
      "env": {
        "BLUESKY_HANDLE": "you.bsky.social",
        "BLUESKY_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Option 2: Install globally from npm

npm install -g bluesky-mcp-server

Claude Desktop Configuration:

{
  "mcpServers": {
    "bluesky": {
      "command": "bluesky-mcp-server",
      "env": {
        "BLUESKY_HANDLE": "you.bsky.social",
        "BLUESKY_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Option 3: Install from source

git clone https://github.com/luminarylane/bluesky-mcp-server.git
cd bluesky-mcp-server
npm install
npm run build

Claude Desktop Configuration:

{
  "mcpServers": {
    "bluesky": {
      "command": "node",
      "args": ["/path/to/bluesky-mcp-server/dist/index.js"],
      "env": {
        "BLUESKY_HANDLE": "you.bsky.social",
        "BLUESKY_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

After updating the config, restart Claude Desktop.

Multi-account Usage

Credentials can be overridden per tool call — useful for managing multiple Bluesky accounts:

Post as alice.bsky.social using handle "alice.bsky.social" and appPassword "aaaa-aaaa-aaaa-aaaa"
Post as bob.bsky.social using handle "bob.bsky.social" and appPassword "bbbb-bbbb-bbbb-bbbb"

💬 Usage

Once configured, ask Claude to:

"What's on my Bluesky timeline?"
"Search Bluesky for posts about #TypeScript"
"Post to Bluesky: 'Hello from Claude!'"
"Reply to that post with a link to example.com"
"Get the profile for user.bsky.social"
"Like and repost the top result"
"What image formats does Bluesky support?"

🛠️ Tools Reference

SENSE Tools (Read)

| Tool | Description | Key Parameters | | ------------------------ | ------------------------------------------ | ------------------------------------- | | bsky_get_timeline | Home timeline from followed accounts | limit (max 50), cursor | | bsky_get_notifications | Likes, reposts, follows, mentions, replies | limit (max 50), cursor | | bsky_search_posts | Search posts by keyword/phrase/hashtag | query, sort (top/latest), limit | | bsky_get_post_thread | Fetch a post and its full thread | uri (AT URI), depth (max 20) | | bsky_get_profile | Get a user's profile | actor (handle or DID) | | bsky_get_followers | List followers of an account | actor, limit (max 100) | | bsky_search_users | Find users by name or keyword | query, limit (max 50) | | bsky_get_feed | Posts from a custom feed generator | feed (AT URI), limit | | bsky_get_media_specs | Platform media format requirements | — |

ACT Tools (Write)

| Tool | Description | Key Parameters | | ------------------ | ------------------------------------------------ | ------------------------------------------- | | bsky_create_post | Create a post (text, link card, image, or video) | text, linkUrl / imageUrl / videoUrl | | bsky_reply | Reply to a post | text, parentUri, parentCid | | bsky_like | Like a post | uri, cid | | bsky_repost | Repost a post | uri, cid | | bsky_follow | Follow a user | did | | bsky_delete_post | Delete a post | uri |

All tools accept optional handle and appPassword arguments to override the environment-variable credentials.

📎 Media Embeds

bsky_create_post supports three embed types (mutually exclusive):

| Type | Parameter | Accepted Formats | Max Size | | ----------------- | ---------- | --------------------------- | ---------- | | Link preview card | linkUrl | Any URL | — | | Image | imageUrl | JPEG, PNG (https:// only) | 1 MB | | Video | videoUrl | MP4 (https:// only) | 50 MB, 60s |

Link preview cards automatically fetch og:title, og:description, and og:image from the target URL.

🔧 Troubleshooting

Common Errors

Missing credentials

Missing credentials — Provide handle + appPassword as arguments, or set BLUESKY_HANDLE and BLUESKY_APP_PASSWORD env vars.

Solution: Set the env vars in your Claude Desktop config, or pass handle and appPassword directly in the tool call.

Auth failed

Auth failed — Bluesky login failed: Invalid identifier or password

Solution: Generate a fresh App Password at bsky.app/settings/app-passwords. App passwords are separate from your account password.

Rate limited

Rate limited — Bluesky API rate limit reached (write bucket). Wait 45s then retry.

Solution: The server includes built-in rate limiting. Wait the indicated number of seconds and retry the same tool call — the retryAfterSeconds field tells you exactly how long.

Post too long

400 Bad Request — POST_TOO_LONG: Text exceeds 300 graphemes. Shorten the text and retry.

Solution: Bluesky's limit is 300 graphemes (not bytes). Shorten the post text.

Image or video URL rejected

URL rejected (not https:// or blocked address)

Solution: imageUrl and videoUrl must use https:// and point to a public internet address. Local or private network URLs are blocked.

Post not found (404)

POST_NOT_FOUND: This post may have been deleted. Skip it and move on.

Solution: The post was deleted after you retrieved its URI. Skip this operation.

Getting AT URIs

Many tools require an AT URI (at://did:plc:xxx/app.bsky.feed.post/yyy). You can obtain one by:

Using bsky_search_posts — each result includes uri and cid
Using bsky_get_timeline — same shape
Using bsky_get_post_thread — the root post's uri is in the response

Reporting Issues

Check existing issues: GitHub Issues

Open a new issue with:

Error: [paste full error message]
Tool: [tool name]
Steps to reproduce: [what you asked Claude to do]
Environment: [OS, Node.js version]

📝 Open an Issue

🤝 Contributing

Contributions are welcome! To get started:

git clone https://github.com/luminarylane/bluesky-mcp-server.git
cd bluesky-mcp-server
npm install
npm test       # Run the test suite
npm run build  # Compile TypeScript

📝 License

MIT License — see LICENSE for details.

🙏 Acknowledgments

Bluesky and the AT Protocol team for building an open social network
Anthropic for the MCP specification