Bluesky

You can run and use the Bluesky MCP server to access Bluesky’s API through a modeled, multi-account session server. It provides reading and writing capabilities, session persistence, optional local Japanese post storage via Jetstream, and practical tools to manage profiles, timelines, posts, and lists from a single, configurable endpoint.

How to use

You operate the Bluesky MCP server through an MCP client. Start the server with a transport method of your choice, then connect your client to the provided MCP URL. Use the session system to manage multiple Bluesky accounts, switching between them when performing actions such as posting, liking, following, or retrieving timelines.

How to install

Prerequisites: Python 3.10 or newer is required. You may also install via a packaging tool to obtain a console script named mcpbluesky.

Step-by-step setup for local development and usage:

# Install dependencies for development or quick run without packaging
pip install -r requirements.txt

# Editable install for development (imports work and the mcpbluesky command is available)
pip install -e .

# Build artifacts for distribution (wheel and source tarball)
python -m build

# Optional quick check of installation
mcpbluesky --help
python -c "import mcpbluesky; print(mcpbluesky.__all__)"

Configuration and startup notes

You can run in multiple modes. The default Jetstream feature is disabled unless explicitly enabled. Sessions are saved to sessions.json, and a default handle is kept for convenience when an explicit handle isn’t provided.

Jetstream integration is optional. Start the server with the Jetstream feature to subscribe and store Japanese-language posts locally. When enabled, the server subscribes to the Jetstream feed and stores posts that pass the Japanese-language check into a local SQLite database.

Starting the server (examples)

From an installed package, you can start with standard HTTP or stdio transports.

Standard input/output transport (stdio): you start a local MCP server and interact through stdio channels.

HTTP transport using streamable-http: you mount the MCP endpoint at a specific path and connect with an MCP client that supports streamable HTTP.

Client sample to verify actions

A simple Python client demonstrates how to list available tools and fetch a profile. It connects to the server via streamable-http and exercises a couple of endpoints to verify basic functionality.

Security and data handling notes

Sensitive data such as access tokens and refresh tokens are stored in sessions.json. Treat this file with care and restrict access to trusted users.

If you enable Jetstream, the receive loop runs in a separate thread. Be mindful of concurrency when inspecting or manipulating shared resources.

Troubleshooting and tips

If you encounter rate limits or transient HTTP errors, the client includes retry logic. Avoid excessive request bursts to remain within reasonable usage patterns.

Available tools

bsky_login

Log in to Bluesky using a handle and optional password; stores the session for subsequent actions.

bsky_logout

Log out of the current session and clear tokens.

bsky_refresh_session

Refresh the current session tokens to keep access valid.

bsky_get_profile

Fetch the profile data for a given handle.

bsky_get_author_feed

Retrieve posts from a specific author with optional pagination.

bsky_get_timeline

Fetch the authenticated user’s timeline; requires authentication.

bsky_post

Create a new post with validation for length and content.

bsky_like

Like a post identified by its URI and CID.

bsky_follow

Follow another actor by its DID.

bsky_unfollow

Unfollow a previously followed actor.

bsky_create_list

Create a new list with a given name and description.

bsky_add_to_list

Add a subject to a specified list.

bsky_search_posts

Search posts based on a query string.

bsky_get_notifications

Fetch recent notifications for the authenticated user.

bsky_get_likes

Retrieve who liked a specific post.

bsky_get_lists

List all lists for a given handle.

bsky_search_users

Search for users by a search term.