npm package: @meowtrix/atproto-mcp
Description: MCP server built for AI agents to interact with the AT Protocol.
Latest version: 0.1.11

# @meowtrix/atproto-mcp

MCP server for interacting with the AT Protocol.

**Built for AI agents.** Interaction guards let you restrict your bot to only engage with followers, other bots, or accounts that @-mention it, so your AI can't go rogue on the network. See [Interaction guards](#interaction-guards).

**Token-efficient responses.** All API responses are automatically slimmed before they reach your agent. Heavy fields like avatars, blob metadata, labels, and full embed details are stripped. Only the essentials come back: identifiers, post text, author handles, engagement counts, and viewer state.

## Quick start (npx)

Add this in your mcp config:

```json
{
  "name": "atproto",
  "command": "npx",
  "args": ["-y", "@meowtrix/atproto-mcp", "--stdio"],
  "env": {
    "ATPROTO_HANDLE": "your-handle.bsky.social",
    "ATPROTO_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
  }
}
```

Generate an app password at [bsky.app/settings/app-passwords](https://bsky.app/settings/app-passwords).

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `ATPROTO_HANDLE` | Yes | -- | Your AT Protocol handle (e.g. `alice.bsky.social`) |
| `ATPROTO_APP_PASSWORD` | Yes | -- | App password (not your main password) |
| `ATPROTO_TOOLS` | No | all | Comma-separated list of tool groups to enable (see [Tool groups](#tool-groups)) |
| `RESTRICT_INTERACTIONS_TO` | No | -- | Comma-separated list of allowed interaction categories (see below) |


## Tool groups

By default all tools are enabled. Set `ATPROTO_TOOLS` to a comma-separated list of groups to only register the tools you need, reducing token usage in LLM context windows.

| Group | Description |
|---|---|
| `protocol` | Low-level AT Protocol tools (records, blobs, DIDs) |
| `bluesky_social` | Core Bluesky social tools (posts, timeline, search, notifications, likes, follows, profile) |
| `bluesky_misc` | Additional Bluesky tools (lists, custom feeds, suggestions, preferences) |
| `bluesky` | Alias for `bluesky_social` + `bluesky_misc` |

**Examples:**

```bash
ATPROTO_TOOLS=protocol                    # only AT Protocol tools
ATPROTO_TOOLS=bluesky_social              # core Bluesky social features
ATPROTO_TOOLS=protocol,bluesky_social     # protocol + social, no misc
ATPROTO_TOOLS=bluesky                     # all Bluesky tools
```

## Interaction guards

When `RESTRICT_INTERACTIONS_TO` is set, the server restricts engagement actions (replies, likes, reposts, follows) to accounts matching at least one listed category. This prevents the AI from interacting with arbitrary accounts unsupervised.

| Category | Description |
|---|---|
| `followers` | Allow interactions with accounts that follow the bot |
| `bots` | Allow interactions with accounts that have [self-labeled as bots](https://github.com/bluesky-social/social-app/pull/10008) |
| `mentions` | Allow interactions when the bot was @-mentioned (in a thread for replies, in the post for likes/reposts) |

Categories combine with **OR logic** — the target must satisfy at least one. For example, `followers,bots` allows interactions with accounts that are followers **or** bots.

**Examples:**

```bash
RESTRICT_INTERACTIONS_TO=followers,mentions     # followers or mentions
RESTRICT_INTERACTIONS_TO=bots                   # bot accounts only
RESTRICT_INTERACTIONS_TO=followers,bots,mentions # any of the three
```

**Always allowed regardless of guards:**
- Interactions with yourself (self-likes, self-replies, etc.)
- Replies to your own threads (if you authored any ancestor post)
- Top-level posts (not replies)

## HTTP mode

Start the server on port 3001:

```bash
npm start
```

Then configure your MCP client to connect via HTTP:

```json
{
  "name": "atproto",
  "url": "http://localhost:3001/mcp"
}
```

## Docker

### Docker Compose

Create a `.env` file with your credentials:

```
ATPROTO_HANDLE=your-handle.bsky.social
ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
```

Then run:

```bash
docker compose up
```

### Manual Docker

```bash
docker build -t atproto-mcp .

docker run -p 3001:3001 \
  -e ATPROTO_HANDLE=your-handle.bsky.social \
  -e ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  atproto-mcp
```

## Resources

| Resource | URI | Description |
|---|---|---|
| My Repo Collections | `repo:///collections` | Shows what record types (collection NSIDs) exist in your AT Protocol repo — useful for discovering what services and data you have |

## Tools

### Protocol

| Tool | Description |
|---|---|
| `whoami` | Check current authenticated session |
| `resolve_did` | Resolve a handle to a DID and fetch DID document |
| `get_record` | Fetch any record by repo/collection/rkey |
| `list_records` | List records in a collection |
| `describe_repo` | Get repo metadata and collections (defaults to your own repo) |
| `get_blob` | Download a blob by DID and CID |
| `upload_blob` | Upload a blob (image, etc.) |
| `create_record` | Create a record in any collection |
| `put_record` | Create or update a record by collection and rkey |
| `delete_record` | Delete a record by collection and rkey |

### Bluesky Social

| Tool | Description |
|---|---|
| `post` | Create a Bluesky post (supports replies and @-mentions) |
| `timeline` | Get your Bluesky home timeline |
| `discover_feed` | Browse the Bluesky Discover feed ("What's Hot") |
| `search_posts` | Search Bluesky posts by keyword |
| `search_users` | Search for Bluesky user accounts |
| `get_profile` | Get a user's Bluesky profile |
| `get_author_feed` | Get a user's Bluesky posts |
| `my_posts` | Get your own recent Bluesky posts |
| `get_post_thread` | Get a post thread with replies |
| `like` | Like a Bluesky post |
| `unlike` | Remove a like from a Bluesky post |
| `repost` | Repost a Bluesky post |
| `unrepost` | Remove a repost |
| `follow` | Follow a Bluesky user |
| `unfollow` | Unfollow a Bluesky user |
| `delete_post` | Delete one of your own Bluesky posts |
| `all_notifications` | List all Bluesky notifications (read and unread) |
| `unread_notifications` | List only unread Bluesky notifications |
| `mark_notifications_read` | Mark all Bluesky notifications as read |
| `get_followers` | List a user's followers |
| `get_follows` | List who a user follows |
| `update_profile` | Update your Bluesky profile (display name, bio, avatar, banner) |

### Bluesky Misc

| Tool | Description |
|---|---|
| `get_lists` | Get a user's lists |
| `get_list` | Get list details and items |
| `get_suggested_follows` | Get follow suggestions |
| `get_suggested_feeds` | Discover suggested custom feeds |
| `get_feed` | Get posts from a custom feed |
| `get_feed_generators` | Look up metadata for one or more feed generators |
| `get_preferences` | Read your account preferences |
| `put_preferences` | Replace all account preferences |