BlueSky MCP Server Interface

A Model Context Protocol (MCP) daemon designed to interface with the BlueSky social ecosystem utilizing its published RESTful endpoints. This implementation conforms to a unified protocol for fetching user metadata and mapping follower relationships.

Core Capabilities

• Obtain granular details of any registered BlueSky user profile
• Query paginated lists representing an actor's subscriptions (following)
• Automated handling of credential exchange and session maintenance
• Robust error reporting mechanisms across all operations

Deployment Instructions

Claude Desktop Configuration

• On macOS systems: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• On Windows platforms: %APPDATA%/Claude/claude_desktop_config.json

Configuration for Pre-Release/Local Servers

"mcpServers": { "bluesky-mcp": { "command": "uv", "args": [ "--directory", "C:\\Users\\{INSERT_USER}\\YOUR\\PATH\\TO\\bluesky-mcp\\bluesky-mcp", "run", "src/bluesky_mcp/server.py" ], "env": { "BLUESKY_IDENTIFIER": "your.handle.bsky.social", "BLUESKY_APP_PASSWORD": "your-app-password" } } }

Local Environment Setup

Prerequisite Software Installation

uv pip install -e .

Server Activation

Once the Claude client is linked to the MCP tooling via the configuration manifest and dependencies are satisfied, the server's exposed routines become available:

You can initiate the service locally via: In the bluesky_mcp repository root:

uv run src/bluesky_mcp/server.py

*To simultaneously run the service endpoint along with the integrated protocol inspector:

npx @modelcontextprotocol/inspector uv --directory C:\Users\{INSERT_USER}\YOUR\PATH\TO\bluesky-mcp run src/bluesky_mcp/server.py

Exposed Functionality

The daemon exposes two distinct methods for external invocation: - get-profile: Retrieves comprehensive identity data pertaining to a specified BlueSky participant. - get-follows: Fetches the collection of external entities subscribed to by a designated account.

get-profile

Resolves and returns detailed attributes associated with a BlueSky user identifier.

Input Payload Schema:

{ "handle": { "type": "string", "description": "The unique account identifier (e.g., 'alice.bsky.social')" } }

Sample Output:

Profile details for alice.bsky.social:

Identifier: alice.bsky.social Nominal Name: Alice Bio Summary: Just a BlueSky user sharing thoughts Follower Count: 1234 Following Count: 567 Post Count: 789

get-follows

Fetches an ordered list of accounts that the specified user is currently tracking, supporting sequential data retrieval.

Input Payload Schema:

{ "actor": { "type": "string", "description": "The user's handle (e.g., 'alice.bsky.social')" }, "limit": { "type": "integer", "description": "Maximum cardinality of records returned per query", "default": 50, "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "description": "Token for advancing to the next page of results", "optional": true } }

Sample Output:

Subscription list for alice.bsky.social:

Subscriptions: Handle: bob.bsky.social Nominal Name: Bob

---

Handle: carol.bsky.social Nominal Name: Carol

---

Handle: dave.bsky.social Nominal Name: Dave

---

Further records are available. Continuation Token: bafygeia...

Fault Tolerance

The service incorporates extensive logic to manage predictable operational failures:

• Credential validation failures
• Traffic throttling constraints
• Network layer communication interruptions
• Malformed input argument rejection
• Latency timeout management
• Inconsistent data structure responses

Failure notifications are rendered in a clear, readily comprehensible format.

Essential Dependencies

• Python interpreter version 3.12 or newer
• The httpx library for asynchronous HTTP operations
• The mcp framework package

Authorization Procedure

To successfully engage with this MCP interface, the following steps are mandatory: 1. Establish an active BlueSky account if one does not already exist. 2. Navigate to the account security section to generate a dedicated Application Password. 3. Configure the following environment variables on the execution host: - BLUESKY_IDENTIFIER: Your registered BlueSky principal identifier (e.g., "username.bsky.social") - BLUESKY_APP_PASSWORD: The securely generated Application Password credential

Contribution Guidelines

We encourage community involvement! Please submit any proposed enhancements or bug fixes via a formal Pull Request.

Licensing Terms

This MCP implementation is distributed under the permissive MIT License. This permits unrestricted utilization, modification, and dissemination of the software, contingent upon adherence to the MIT License stipulations. Detailed terms are available within the repository's LICENSE file.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea