@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.

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:

{
  "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.

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) | | 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:

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 | | 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:

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:

npm start

Then configure your MCP client to connect via HTTP:

{
  "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:

docker compose up

Manual Docker

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 |