BlueSky MCP Server

How to use

Install the server and run it locally, then connect your MCP client to the server to use its tools. You will primarily use two tools: get-profile to fetch detailed profile information for a user, and get-follows to retrieve the list of accounts that a user follows with pagination.

Prerequisites for typical usage: ensure Python 3.12 or higher is available, and you have access to the MCP tooling in your environment. You will authenticate by providing your BlueSky credentials via environment variables when starting the server.

Common usage patterns include obtaining a user profile by handle and then listing a user’s follows to build a view of their network. If you need more results beyond the initial page, use the cursor provided by the server to fetch subsequent pages.

If you want to explore the server locally alongside a server inspector, you can start the inspector together with the server to monitor activity and requests in real time.

How to install

Prerequisites you need before installation: Python 3.12 or higher, and the MCP tooling installed in your environment.

uv pip install -e .

Install or prepare dependencies for the Bluesky MCP server. This step ensures the server code is ready to run in your environment.

Run the server locally using the runtime command provided. This starts the MCP server and makes its tools available to your MCP client.

uv run src/bluesky_mcp/server.py

If you want to run the server inspector alongside the server, use the inspector command with the appropriate directory to observe the server activity.

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

Additional configuration and notes

Authentication is handled via environment variables set when starting the server. Specifically, you will need to provide your BlueSky identifier and app password to authorize requests.

Environment variables you will set for runtime: BLUESKY_IDENTIFIER and BLUESKY_APP_PASSWORD. Use your own BlueSky handle and app password in those values.

The server exposes two tools to MCP clients with straightforward input fields: get-profile and get-follows. Each tool returns structured data that can be consumed by your MCP client for display or further processing.

If you encounter authentication failures, rate limiting, network issues, invalid parameters, timeouts, or malformed responses, the server provides clear error messages to help you identify and fix the problem.

Security note: protect your BlueSky App Password and do not expose environment variables in unsecured contexts. Rotate credentials if you suspect they have been compromised.

Example configuration snippet for local development shows how the MCP server is wired and which environment variables are used.

Example configuration snippet for development

{
  "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"
      }
    }
  }
}

get-profile

Fetches detailed profile information for a specified BlueSky user handle.

get-follows

Retrieves a list of accounts that a specified user follows with support for pagination.