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

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