home / mcp / bluesky mcp server
Provides Bluesky API access through an MCP server with multi-account sessions, optional local Japanese post storage, and practical tools to read and write data.
Configuration
View docs{
"mcpServers": {
"awaku7-mcpbluesky": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"BSKY_HANDLE": "YOUR_HANDLE",
"BSKY_APP_PASSWORD": "YOUR_APP_PASSWORD"
}
}
}
}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.
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.
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__)"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.
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.
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.
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.
If you encounter rate limits or transient HTTP errors, the client includes retry logic. Avoid excessive request bursts to remain within reasonable usage patterns.
Log in to Bluesky using a handle and optional password; stores the session for subsequent actions.
Log out of the current session and clear tokens.
Refresh the current session tokens to keep access valid.
Fetch the profile data for a given handle.
Retrieve posts from a specific author with optional pagination.
Fetch the authenticated user’s timeline; requires authentication.
Create a new post with validation for length and content.
Like a post identified by its URI and CID.
Follow another actor by its DID.
Unfollow a previously followed actor.
Create a new list with a given name and description.
Add a subject to a specified list.
Search posts based on a query string.
Fetch recent notifications for the authenticated user.
Retrieve who liked a specific post.
List all lists for a given handle.
Search for users by a search term.