Bluesky Context Server

1# Bluesky Context Server
2[![smithery badge](https://smithery.ai/badge/bluesky-context-server)](https://smithery.ai/server/bluesky-context-server)
3 
4A 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.
5 
6## Prerequisites
7 
8- **Runtime**: Either [Bun](https://bun.sh/) or [Node.js](https://nodejs.org/) v22.6.0+
9- A Bluesky account
10 
11## Setup
12 
13### 1. Get Your Bluesky Credentials
14 
15You'll need two pieces of information from your Bluesky account:
16 
17#### BLUESKY_IDENTIFIER
18This is your Bluesky handle (username). It can be in either format:
19- `username.bsky.social` (e.g., `alice.bsky.social`)
20- `@username.bsky.social` (e.g., `@alice.bsky.social`)
21 
22#### BLUESKY_APP_KEY
23This is an App Password, which is different from your regular Bluesky password. To create one:
24 
251. Go to [Bluesky Settings](https://bsky.app/settings)
262. Navigate to "Privacy and Security" → "App Passwords"
273. Click "Add App Password"
284. Give it a name (e.g., "MCP Server")
295. Copy the generated password (it looks like `xxxx-xxxx-xxxx-xxxx`)
30 
31⚠️ **Important**: Use the App Password, not your regular account password!
32 
33### 2. Installation
34 
35#### Option A: Installing via Smithery (Recommended)
36 
37To install Bluesky Context Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@laulauland/bluesky-context-server):
38 
39```bash
40npx -y @smithery/cli install @laulauland/bluesky-context-server --client claude
41```
42 
43Then add your credentials to the generated configuration.
44 
45#### Option B: Manual Installation
46 
471. Clone or download this repository
482. Configure your Claude Desktop app to use the MCP server:
49 
50**Using Bun:**
51```json
52// ~/Library/Application Support/Claude/config.json (macOS)
53// %APPDATA%/Claude/config.json (Windows)
54{
55	"mcpServers": {
56		"bluesky": {
57			"command": "/Users/your-username/.bun/bin/bun",
58			"args": [
59				"/path/to/bluesky-context-server/packages/server/bin/index.ts"
60			],
61			"env": {
62				"BLUESKY_APP_KEY": "your-app-password-here",
63				"BLUESKY_IDENTIFIER": "your-handle.bsky.social"
64			}
65		}
66	}
67}
68```
69 
70**Using Node.js:**
71```json
72// ~/Library/Application Support/Claude/config.json (macOS)
73// %APPDATA%/Claude/config.json (Windows)
74{
75	"mcpServers": {
76		"bluesky": {
77			"command": "node",
78			"args": [
79				"--experimental-strip-types",
80				"/path/to/bluesky-context-server/packages/server/bin/index.ts"
81			],
82			"env": {
83				"BLUESKY_APP_KEY": "your-app-password-here",
84				"BLUESKY_IDENTIFIER": "your-handle.bsky.social"
85			}
86		}
87	}
88}
89```
90 
913. Restart Claude Desktop
92 
93### 3. Testing the Connection
94 
95After setup, you can test the connection by asking Claude something like:
96- "Can you get my Bluesky profile?"
97- "Show me my recent posts on Bluesky"
98- "Search for posts about AI on Bluesky"
99 
100## Available MCP Tools
101 
102This server provides the following tools that Claude can use:
103 
104### Profile & Account Tools
105 
106#### `bluesky_get_profile`
107Get your Bluesky profile information including display name, bio, follower count, etc.
108- **Parameters**: None
109- **Returns**: Complete profile data
110 
111#### `bluesky_get_follows`
112Get a list of accounts you follow.
113- **Parameters**: 
114  - `limit` (optional): Max items to return (default 50, max 100)
115  - `cursor` (optional): Pagination cursor for next page
116- **Returns**: List of followed accounts with profile info
117 
118#### `bluesky_get_followers`
119Get a list of accounts following you.
120- **Parameters**: 
121  - `limit` (optional): Max items to return (default 50, max 100)
122  - `cursor` (optional): Pagination cursor for next page
123- **Returns**: List of followers with profile info
124 
125### Post & Feed Tools
126 
127#### `bluesky_get_posts`
128Get your recent posts.
129- **Parameters**: 
130  - `limit` (optional): Max items to return (default 50, max 100)
131  - `cursor` (optional): Pagination cursor for next page
132- **Returns**: Your recent posts with engagement data
133 
134#### `bluesky_get_personal_feed`
135Get your personalized Bluesky timeline/feed.
136- **Parameters**: 
137  - `limit` (optional): Max items to return (default 50, max 100)
138  - `cursor` (optional): Pagination cursor for next page
139- **Returns**: Posts from your personalized feed
140 
141#### `bluesky_get_liked_posts`
142Get posts you've liked.
143- **Parameters**: 
144  - `limit` (optional): Max items to return (default 50, max 100)
145  - `cursor` (optional): Pagination cursor for next page
146- **Returns**: Posts you've liked
147 
148### Search Tools
149 
150#### `bluesky_search_posts`
151Search for posts across Bluesky.
152- **Parameters**: 
153  - `query` (required): Search query string
154  - `limit` (optional): Max items to return (default 50, max 100)
155  - `cursor` (optional): Pagination cursor for next page
156- **Returns**: Posts matching your search query
157 
158#### `bluesky_search_profiles`
159Search for Bluesky user profiles.
160- **Parameters**: 
161  - `query` (required): Search query string
162  - `limit` (optional): Max items to return (default 50, max 100)
163  - `cursor` (optional): Pagination cursor for next page
164- **Returns**: User profiles matching your search query
165 
166## Example Usage
167 
168Once configured, you can ask Claude things like:
169 
170- "What's in my Bluesky feed today?"
171- "Search for posts about TypeScript on Bluesky"
172- "Who are my most recent followers?"
173- "Show me posts I've liked recently"
174- "Find Bluesky users interested in AI"
175 
176## Troubleshooting
177 
178### Common Issues
179 
1801. **"Authentication failed"**: Double-check your `BLUESKY_APP_KEY` and `BLUESKY_IDENTIFIER`
1812. **"Server not responding"**: Ensure Bun is installed and the path to the server is correct
1823. **"Permission denied"**: Make sure the server file has execute permissions
183 
184### Getting Help
185 
186If you encounter issues:
1871. Check that your Bluesky credentials are correct
1882. Verify Bun is installed: `bun --version`
1893. Test the server manually: `cd packages/server && bun start`
1904. Check Claude Desktop's logs for error messages
191