# bluesky-mcp

An MCP (Model Context Protocol) server for managing a Bluesky account from Claude (or any
MCP-compatible client): post, reply, like, repost, follow/unfollow, search, and read your
timeline/notifications. Uses the official AT Protocol API with a handle + app password — no
OAuth app, no approval process required, and works even with 2FA enabled since it never touches
your real account password.

The original one-off `post.js` CLI script is still here and still works if you just want to fire
off a single post from the terminal without going through Claude.

## Setup

1. Clone the repo and install dependencies:
   ```
   git clone https://github.com/AhmadTariq1337/bluesky-mcp.git
   cd bluesky-mcp
   npm install
   ```
2. Copy `.env.example` to `.env` and add your handle + app password (get an app password from
   Bluesky: Settings → Privacy and Security → App Passwords):
   ```
   cp .env.example .env
   ```
3. Register it as an MCP server in your client's config. For Claude Desktop
   (`claude_desktop_config.json`):
   ```json
   "bluesky": {
     "command": "node",
     "args": ["/absolute/path/to/bluesky-mcp/index.js"]
   }
   ```
4. Restart Claude Desktop (fully quit from the tray, not just close the window) so it picks up
   the new server.

## Tools exposed

| Tool | Does |
|---|---|
| `bluesky_get_timeline` | Get your home feed (scroll) |
| `bluesky_get_author_feed` | Get a user's posts |
| `bluesky_search_posts` | Search public posts |
| `bluesky_get_post` | Get post details incl. the `cid` needed to like/repost |
| `bluesky_get_profile` | Get profile info |
| `bluesky_get_followers` / `bluesky_get_following` | List a user's followers / follows |
| `bluesky_get_notifications` / `bluesky_mark_notifications_read` | Read/clear notifications |
| `bluesky_resolve_handle` | Look up a DID from a handle |
| `bluesky_post` | Post, optionally as a reply |
| `bluesky_delete_post` | Delete your own post |
| `bluesky_like` / `bluesky_unlike` | Like / undo a like |
| `bluesky_repost` / `bluesky_unrepost` | Repost / undo a repost |
| `bluesky_follow` / `bluesky_unfollow` | Follow / unfollow (by DID) |

For the "un-" actions, pass the AT-URI of the *record itself* (the like/repost/follow record,
returned in `viewer.like` / `viewer.repost` / `viewer.following` on posts and profiles) — not the
original post or account's URI.

## Standalone CLI (no Claude needed)

```
node post.js "Just shipped a new project, check it out!"
```

(`npm run post-cli -- "text"` works the same way.) Prints a link to the live post. 300 character
limit, checked before sending.

## Security

- `.env` holds your real handle and app password, and is gitignored — never commit it.
- App passwords are scoped and revocable from Bluesky's settings, unlike your main account
  password.

## License

MIT