bluesky-daily-mcp

An MCP Server to help you surface the most interesting topics from your Bluesky follows daily.

For examples of how to use, please visit "Building an MCP Server to Explore My Bluesky Feed".

Features

• a tool to retrieve all posts from your follows for a given day
• sample prompts for analyzing posts
• caches the posts for a given day

Follows and Posts are retrieved via bsky-tldr npm package which both (a) shaves down infomation to just the key fields, and (b) ensures posts are efficiently retrieved for only the day requested.

In this MCP Server, we add more descriptive field names and combine author and post information together for easy consumption by the LLM:

type StandalonePost = {
  urlToOriginalPost: string;
  authorIdentifier: string;
  authorNameOrHandle: string;
  content: string;
  links: string[];
  isRepost: boolean;
};

Limitations

• This retrieves all posts from your follows for a given day. This will become large and subsequently you'll lose posts that are truncated by the MCP Client or the LLM's context window. Will need additional strategies to handle this.

• You'll run into Bluesky API rate limits and/or timeouts if you try to retrieve posts from historic dates, say weeks or months ago. bsky-tldr package is smart enough to stop retrieving posts older than the day requested, but does need to retrieve all the newer ones on its way to the historic date.

Installation

Install this MCP Server with your MCP Client, such as Claude Desktop.

Here are the steps:

👉 1. Configure. For Claude Desktop, you can install this MCP Server by adding the following to your ~/Library/Application\ Support/Claude/claude_desktop_config.json (on MacOS):

Option A: Run from NPM package

NOTE: PATH pointing to the absolute path to the /bin folder where npx is running is only needed if you use NVM to manage your Node.js versions. Without that, you may see a mysterious "Header not set" error. Find path via which npx command.

{
  "mcpServers": [
    "bluesky-daily-mcp": {
      "command": "npx",
      "args": ["-y", "bluesky-daily-mcp"],
      "env": {
        "PATH": "/absolute/path/to/npx/bin:/usr/bin:/bin",
        "BLUESKY_HANDLE": "",
        "BLUESKY_APP_PASSWORD": "",
        "TIMEZONE_OFFSET": "-8",
        "REQUEST_TIMEOUT_MS": "120000"
      }
    }
  ]
}

Option B: Clone repo and run it from source

Build the MCP Server first in the cloned repo:

npm install
npm run build

NOTE: the /absolute/path is needed to node if you use NVM to manage your Node.js versions. Without that, you may see a mysterious "Header not set" error. Find path via which node command.

{
  "mcpServers": [
    "bluesky-daily-mcp": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/this/dist/index.js"],
      "env": {
        "BLUESKY_HANDLE": "",
        "BLUESKY_APP_PASSWORD": "",
        "TIMEZONE_OFFSET": "-8",
        "REQUEST_TIMEOUT_MS": "120000"
      }
    }
  ]
}

What are these env variables?

• BLUESKY_HANDLE is your Bluesky handle without the @ sign, e.g. your_handle.bsky.social or customdomain.com.
• BLUESKY_APP_PASSWORD is a Bluesky app password, which you can generate from the Bluesky App Passwords Settings page.
• TIMEZONE_OFFSET is the timezone offset from UTC in hours. For example, -8 for PST, +8 for CST. This helps define what a "day" is for you, so it's not hard-coded to UTC.
• REQUEST_TIMEOUT_MS is the max timeout for the request that retrieves the posts to run. Without this, you have a default of ~60 seconds (60000 ms). Recommend setting this to 2 minutes (120000 ms).

👉 2. Restart Claude Desktop to load up new MCP Server.

Try it out

• Fire up Claude Desktop and start a new conversation
• Type in "Retrieve Bluesky posts from yesterday" or "Retrieve Bluesky posts from April 2nd" (or whatever date you want)

Help for Contributors

Running locally for development

Setup your local .env file with:

BLUESKY_HANDLE=
BLUESKY_APP_PASSWORD=
TIMEZONE_OFFSET=

Debug with MCP Inspector:

npm install
npm run build && npx @modelcontextprotocol/inspector -e BLUESKY_HANDLE=XXX -e BLUESKY_APP_PASSWORD=XXX -e TIMEZONE_OFFSET=XXX node dist/index.js
```

Debug by viewing logs

```bash
tail -n 20 -F ~/Library/Logs/Claude/mcp-server-bluesky-daily-mcp.log

Run tests or coverage reports

npm test
npm run coverage

Manually retrieve posts

If you want to make sure the post retrieval code is running ok with your .env, run:

npm run retrieve-posts

Steps for publishing package to NPM

After merging latest code to main branch:

1. Locally, git checkout main && git pull
2. npm version patch # or minor, or major
3. git push --follow-tags
4. A GitHub release is automatically written and published