Bluesky Context Server

A Model Context Protocol (MCP) server that enables MCP clients like Claude Desktop to interact with Bluesky. Query your profile, search posts, get your timeline, and more directly from your AI assistant.

Prerequisites

Runtime: Either Bun or Node.js v22.6.0+
A Bluesky account

Setup

1. Get Your Bluesky Credentials

You'll need two pieces of information from your Bluesky account:

BLUESKY_IDENTIFIER

This is your Bluesky handle (username). It can be in either format:

username.bsky.social (e.g., alice.bsky.social)
@username.bsky.social (e.g., @alice.bsky.social)

BLUESKY_APP_KEY

This is an App Password, which is different from your regular Bluesky password. To create one:

Go to Bluesky Settings
Navigate to "Privacy and Security" → "App Passwords"
Click "Add App Password"
Give it a name (e.g., "MCP Server")
Copy the generated password (it looks like xxxx-xxxx-xxxx-xxxx)

⚠️ Important: Use the App Password, not your regular account password!

2. Installation

Option A: Installing via Smithery (Recommended)

To install Bluesky Context Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @laulauland/bluesky-context-server --client claude

Then add your credentials to the generated configuration.

Option B: Manual Installation

Clone or download this repository
Configure your Claude Desktop app to use the MCP server:

Using Bun:

// ~/Library/Application Support/Claude/config.json (macOS)
// %APPDATA%/Claude/config.json (Windows)
{
	"mcpServers": {
		"bluesky": {
			"command": "/Users/your-username/.bun/bin/bun",
			"args": [
				"/path/to/bluesky-context-server/packages/server/bin/index.ts"
			],
			"env": {
				"BLUESKY_APP_KEY": "your-app-password-here",
				"BLUESKY_IDENTIFIER": "your-handle.bsky.social"
			}
		}
	}
}

Using Node.js:

// ~/Library/Application Support/Claude/config.json (macOS)
// %APPDATA%/Claude/config.json (Windows)
{
	"mcpServers": {
		"bluesky": {
			"command": "node",
			"args": [
				"--experimental-strip-types",
				"/path/to/bluesky-context-server/packages/server/bin/index.ts"
			],
			"env": {
				"BLUESKY_APP_KEY": "your-app-password-here",
				"BLUESKY_IDENTIFIER": "your-handle.bsky.social"
			}
		}
	}
}

Restart Claude Desktop

3. Testing the Connection

After setup, you can test the connection by asking Claude something like:

"Can you get my Bluesky profile?"
"Show me my recent posts on Bluesky"
"Search for posts about AI on Bluesky"

Available MCP Tools

This server provides the following tools that Claude can use:

Profile & Account Tools

`bluesky_get_profile`

Get your Bluesky profile information including display name, bio, follower count, etc.

Parameters: None
Returns: Complete profile data

`bluesky_get_follows`

Get a list of accounts you follow.

Parameters:
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: List of followed accounts with profile info

`bluesky_get_followers`

Get a list of accounts following you.

Parameters:
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: List of followers with profile info

Post & Feed Tools

`bluesky_get_posts`

Get your recent posts.

Parameters:
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: Your recent posts with engagement data

`bluesky_get_personal_feed`

Get your personalized Bluesky timeline/feed.

Parameters:
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: Posts from your personalized feed

`bluesky_get_liked_posts`

Get posts you've liked.

Parameters:
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: Posts you've liked

Search Tools

`bluesky_search_posts`

Search for posts across Bluesky.

Parameters:
- query (required): Search query string
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: Posts matching your search query

`bluesky_search_profiles`

Search for Bluesky user profiles.

Parameters:
- query (required): Search query string
- limit (optional): Max items to return (default 50, max 100)
- cursor (optional): Pagination cursor for next page
Returns: User profiles matching your search query

Example Usage

Once configured, you can ask Claude things like:

"What's in my Bluesky feed today?"
"Search for posts about TypeScript on Bluesky"
"Who are my most recent followers?"
"Show me posts I've liked recently"
"Find Bluesky users interested in AI"

Troubleshooting

Common Issues

"Authentication failed": Double-check your BLUESKY_APP_KEY and BLUESKY_IDENTIFIER
"Server not responding": Ensure Bun is installed and the path to the server is correct
"Permission denied": Make sure the server file has execute permissions

Getting Help

If you encounter issues:

Check that your Bluesky credentials are correct
Verify Bun is installed: bun --version
Test the server manually: cd packages/server && bun start
Check Claude Desktop's logs for error messages

Bluesky Context Server