Bluesky MCP server

The Bluesky Context Server is a Model Context Protocol (MCP) server that connects your AI assistant, like Claude Desktop, to your Bluesky account. It allows your AI to access your Bluesky profile, search for posts, view your timeline, and perform other interactions directly from your conversations.

Prerequisites

Before getting started, you'll need:

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

Getting Your Bluesky Credentials

You'll need two pieces of information:

BLUESKY_IDENTIFIER

This is your Bluesky handle in either format:

• username.bsky.social
• @username.bsky.social

BLUESKY_APP_KEY

This is an App Password (different from your regular password):

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

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

Installation

Option A: Installing via Smithery (Recommended)

To install 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

1. Clone or download the repository
2. Configure your Claude Desktop app with the following settings:

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

3. Restart Claude Desktop

Testing the Connection

After setup, test the connection by asking Claude:

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

Available Tools

Profile & Account Tools

bluesky_get_profile

Get your Bluesky profile information.

• 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:

• "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

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

If you encounter problems:

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "bluesky" '{"command":"bun","args":["index.ts"],"env":{"BLUESKY_APP_KEY":"","BLUESKY_IDENTIFIER":""}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "bluesky": {
            "command": "bun",
            "args": [
                "index.ts"
            ],
            "env": {
                "BLUESKY_APP_KEY": "",
                "BLUESKY_IDENTIFIER": ""
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "bluesky": {
            "command": "bun",
            "args": [
                "index.ts"
            ],
            "env": {
                "BLUESKY_APP_KEY": "",
                "BLUESKY_IDENTIFIER": ""
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect