Bluesky

This Bluesky MCP Server is a lightweight Python implementation of the Model Context Protocol (MCP) that enables AI agents to interact with the Bluesky network efficiently. It focuses on context optimization, Windows-friendly IO, and a complete set of MCP tools and resources so your agent can read timelines, post, reply, search, and manage social connections with minimal token overhead.

How to use

You run the Bluesky MCP Server locally and connect your MCP client to it. The server exposes a standard MCP surface that lets your agent observe timelines and notifications, create and reply to posts, manage relationships, and perform targeted searches. The included system prompt guidance helps your agent act with identity anchoring and a proactive, agent-like behavior while using the built-in tools.

Key usage patterns you’ll implement in your agent workflow: observe your timeline with get_timeline, check for new interactions with get_notifications, compose posts with send_post or respond with reply_to_post, manage relationships using follow_user, and discover new content with search_posts. For ongoing situational awareness, you’ll also reference get_current_profile_resource for your current state and get_unread_count_resource for unread activity.

When integrating, map each MCP tool to the corresponding social action within Bluesky. Treat tools as extensions of your agent’s senses and capabilities rather than external API calls. Maintain a consistent voice and keep your interactions in context with your current Bluesky identity.

How to install

pip install -r requirements.txt

# Optional: prepare an environment for local testing
# Create a .env in the repository root if you want to run tests without an MCP client
# BLUESKY_HANDLE=your_handle.bsky.social
# BLUESKY_PASSWORD=your_app_password

python path/to/mcp-server-bluesky-py/bluesky_mcp.py

# If you need the wrapper for Windows environments, you can use the provided entry point
python path/to/mcp-server-bluesky-py/mcp_wrapper.py
"""

Configuration and running tips

Configure the MCP client to load the Bluesky MCP server with the following standard configuration snippet. It wires the Python command to run the Bluesky MCP script and provides the required environment credentials.

{
  "mcpServers": {
    "bluesky": {
      "command": "python",
      "args": [
        "path/to/mcp-server-bluesky-py/bluesky_mcp.py"
      ],
      "env": {
        "BLUESKY_HANDLE": "your_handle.bsky.social",
        "BLUESKY_PASSWORD": "your_app_password"
      }
    }
  }
}

Notes on Windows compatibility and IO

The Bluesky MCP Server includes Windows-friendly handling for stdin/stdout binary streams to prevent common Windows communication issues. If you work in environments with strict Windows IO semantics, consider using the mcp_wrapper entry to ensure stable binary IO during MCP exchanges.

Security and credentials

Store your Bluesky app password securely and avoid embedding the main login password in configurations. Use App Passwords as described when configuring BLUESKY_PASSWORD.

Troubleshooting

If you encounter errors related to communication or token handling, verify that the environment variables are set correctly and that the Bluesky handle is reachable. Ensure you are using the correct script path in the configuration and that the MCP client is configured to load the bluesky MCP server as shown in the configuration snippet.

Examples of common workflows

1. View your home timeline and respond to a post with a short reply using send_post or reply_to_post when appropriate.

2. Scan notifications with get_notifications and acknowledge items by replying or liking where suitable.

3. Discover new content by executing search_posts with a topic keyword and then engage with interesting posts.

Available tools

get_timeline

Fetch the user's home timeline so the agent can observe recent posts and plan engagement.

get_notifications

Retrieve notifications to know who interacted with you or mentioned you.

send_post

Publish a new post on Bluesky from the agent.

reply_to_post

Post a reply to an existing post to participate in conversations.

follow_user

Follow another user to establish a social connection.

search_posts

Search Bluesky posts by keywords to discover relevant content.

get_current_profile_resource

Get the current profile status to reflect identity and presence.

get_unread_count_resource

Provide a count of unread notifications or messages.

like_post

Like a post to show appreciation without composing a reply.