# AT Protocol MCP Server

> A comprehensive Model Context Protocol (MCP) server for AT Protocol integration, enabling LLMs to interact directly with the AT Protocol ecosystem including Bluesky and other decentralized social networks.

This MCP server provides a bridge between Large Language Models and the AT Protocol, allowing LLMs to perform social operations, retrieve data, and manage content on the decentralized social web. It exposes 51 tools, 3 resources plus 2 parameterized resource templates, and 2 prompts, and declares the completions capability. The default transport is stdio; --transport http serves the MCP Streamable HTTP transport at /mcp instead (loopback binding by default).

Key capabilities:
- Full AT Protocol integration using official @atproto/api
- MCP-compliant server implementation with @modelcontextprotocol/sdk
- Type-safe TypeScript implementation with comprehensive validation
- App password authentication (supported); OAuth login is planned but not yet functional
- Extensive social operations (posts, likes, reposts, follows, reply/quote controls via threadgate/postgate)
- Bluesky direct messages (chat.bsky.convo), private bookmarks, and starter pack discovery
- Content management (images, videos, rich text)
- User profile, timeline, and notification access
- Analytics and discovery tools (engagement, network, trending, recommendations)
- Real-time firehose streaming is not exposed and not planned as tools (the unused firehose client code was removed; any future event consumption would be built on Jetstream — see Experimental & Roadmap)

## Getting Started

- [Installation Guide](https://cameronrye.github.io/atproto-mcp/guide/installation.html): How to install and set up the MCP server
- [Quick Start](https://cameronrye.github.io/atproto-mcp/guide/getting-started.html): Get up and running in minutes
- [Configuration](https://cameronrye.github.io/atproto-mcp/guide/configuration.html): Configure the server for your needs
- [Authentication](https://cameronrye.github.io/atproto-mcp/guide/authentication.html): Set up app password authentication (OAuth is experimental)
- [Introduction](https://cameronrye.github.io/atproto-mcp/guide/introduction.html): Overview of the project and its goals

## Core Concepts

- [MCP Protocol](https://cameronrye.github.io/atproto-mcp/guide/mcp-protocol.html): Understanding the Model Context Protocol
- [AT Protocol](https://cameronrye.github.io/atproto-mcp/guide/at-protocol.html): Overview of the AT Protocol ecosystem
- [Tools & Resources](https://cameronrye.github.io/atproto-mcp/guide/tools-resources.html): Available MCP tools and resources
- [Error Handling](https://cameronrye.github.io/atproto-mcp/guide/error-handling.html): Best practices for error handling

## API Reference

- [API Overview](https://cameronrye.github.io/atproto-mcp/api/): Complete API documentation

The server registers **51 tools**. Most require authentication; a small number of public/enhanced tools (notably `get_user_profile`, `search_actors`, `get_author_feed`, `get_user_connections`, `search_starter_packs`, and `get_starter_pack`) also work in unauthenticated mode. `search_posts` requires authentication — the AT Protocol search API changed in 2025 to require auth. OAuth login is planned but not yet functional, so it is not exposed as a tool; real-time streaming is not planned as tools.

### Social Operations
- [Create Post](https://cameronrye.github.io/atproto-mcp/api/tools/create-post.html): Create posts with text, auto-detected or explicit richtext facets, replies, image/external/video embeds, quote posts, and reply/quote controls (threadgate/postgate via `replyControls`/`quoteControls`)
- [Create Thread](https://cameronrye.github.io/atproto-mcp/api/tools/create-thread.html): Create a multi-post thread (optional `replyControls` gate the root post)
- [Reply to Post](https://cameronrye.github.io/atproto-mcp/api/tools/reply-to-post.html): Reply to existing posts
- [Like Post](https://cameronrye.github.io/atproto-mcp/api/tools/like-post.html): Like posts
- [Unlike Post](https://cameronrye.github.io/atproto-mcp/api/tools/unlike-post.html): Remove likes from posts
- [Repost](https://cameronrye.github.io/atproto-mcp/api/tools/repost.html): Repost content
- [Unrepost](https://cameronrye.github.io/atproto-mcp/api/tools/unrepost.html): Remove reposts

### Batch Operations
- [Batch Action](https://cameronrye.github.io/atproto-mcp/api/tools/batch-action.html): Apply one action (`follow`, `like`, or `repost`) across up to 25 targets in one call

### User Management
- [Follow User](https://cameronrye.github.io/atproto-mcp/api/tools/follow-user.html): Follow users
- [Unfollow User](https://cameronrye.github.io/atproto-mcp/api/tools/unfollow-user.html): Unfollow users
- [Get User Profile](https://cameronrye.github.io/atproto-mcp/api/tools/get-user-profile.html): Retrieve user profiles
- [Update Profile](https://cameronrye.github.io/atproto-mcp/api/tools/update-profile.html): Update user profiles
- [Search Actors](https://cameronrye.github.io/atproto-mcp/api/tools/search-actors.html): Find accounts by handle or display name
- [Block User](https://cameronrye.github.io/atproto-mcp/api/tools/block-user.html): Block users
- [Unblock User](https://cameronrye.github.io/atproto-mcp/api/tools/unblock-user.html): Unblock users
- [Mute User](https://cameronrye.github.io/atproto-mcp/api/tools/mute-user.html): Mute users
- [Unmute User](https://cameronrye.github.io/atproto-mcp/api/tools/unmute-user.html): Unmute users

### Data Retrieval
- [Search Posts](https://cameronrye.github.io/atproto-mcp/api/tools/search-posts.html): Search for posts across the network
- [Get Timeline](https://cameronrye.github.io/atproto-mcp/api/tools/get-timeline.html): Retrieve user timelines
- [Get Author Feed](https://cameronrye.github.io/atproto-mcp/api/tools/get-author-feed.html): List a specific user's posts
- [Get User Connections](https://cameronrye.github.io/atproto-mcp/api/tools/get-user-connections.html): Get followers or follows via `direction: 'followers' | 'follows'`
- [Get Notifications](https://cameronrye.github.io/atproto-mcp/api/tools/get-notifications.html): Retrieve notifications (use `countOnly: true` for a cheap unread count)
- [Mark Notifications Seen](https://cameronrye.github.io/atproto-mcp/api/tools/mark-notifications-seen.html): Mark notifications as seen up to a timestamp
- [Get Custom Feed](https://cameronrye.github.io/atproto-mcp/api/tools/get-custom-feed.html): Access custom feeds

### Direct Messages
These call the Bluesky chat service (chat.bsky.convo) and require an app password created with "Allow access to your direct messages" enabled:
- [List Conversations](https://cameronrye.github.io/atproto-mcp/api/tools/list-conversations.html): List your DM conversations (filter by `status: 'request' | 'accepted'`)
- [Get Conversation Messages](https://cameronrye.github.io/atproto-mcp/api/tools/get-conversation-messages.html): Read a conversation's message history
- [Send Direct Message](https://cameronrye.github.io/atproto-mcp/api/tools/send-direct-message.html): Send a direct message to a conversation

### Bookmarks
Bookmarks are private to your account; other users cannot see them:
- [Add Bookmark](https://cameronrye.github.io/atproto-mcp/api/tools/add-bookmark.html): Privately bookmark a post
- [Remove Bookmark](https://cameronrye.github.io/atproto-mcp/api/tools/remove-bookmark.html): Remove a bookmark
- [Get Bookmarks](https://cameronrye.github.io/atproto-mcp/api/tools/get-bookmarks.html): List your bookmarks

### Starter Packs
Both work without authentication (enhanced tools):
- [Search Starter Packs](https://cameronrye.github.io/atproto-mcp/api/tools/search-starter-packs.html): Search Bluesky starter packs by keyword
- [Get Starter Pack](https://cameronrye.github.io/atproto-mcp/api/tools/get-starter-pack.html): Fetch a starter pack's details by AT-URI or bsky.app link

### Content Management
- [Delete Post](https://cameronrye.github.io/atproto-mcp/api/tools/delete-post.html): Delete posts
- [Upload Image](https://cameronrye.github.io/atproto-mcp/api/tools/upload-image.html): Upload images — the returned blob descriptor feeds create_post `embed.images[].image`, `embed.external.thumb`, and update_profile `avatar`/`banner`
- [Upload Video](https://cameronrye.github.io/atproto-mcp/api/tools/upload-video.html): Upload videos
- [Generate Link Preview](https://cameronrye.github.io/atproto-mcp/api/tools/generate-link-preview.html): Generate link previews — the returned `preview.thumb.blob` feeds create_post `embed.external.thumb`
- [Analyze Image](https://cameronrye.github.io/atproto-mcp/api/tools/analyze-image.html): Report a blob's declared size and MIME type (does not decode pixels — no dimensions/aspect ratio)

### Analytics & Discovery
- [Analyze Account](https://cameronrye.github.io/atproto-mcp/api/tools/analyze-account.html): Analyze a single account along one dimension (`engagement`, `network`, or `strategy`)
- [Find Influential Users](https://cameronrye.github.io/atproto-mcp/api/tools/find-influential-users.html): Identify influential accounts in a network
- [Find Similar Users](https://cameronrye.github.io/atproto-mcp/api/tools/find-similar-users.html): Find similar users by shared follows/followers (graph-only; not content-based)
- [Discover](https://cameronrye.github.io/atproto-mcp/api/tools/discover.html): Surface timeline content via `mode: 'trending' | 'recommended'` (caller's own home timeline sample, not network-wide)
- [Discover Communities](https://cameronrye.github.io/atproto-mcp/api/tools/discover-communities.html): Discover communities/clusters in a network
- [Get User Summary](https://cameronrye.github.io/atproto-mcp/api/tools/get-user-summary.html): Summarize a user's profile and activity
- [Get Post Context](https://cameronrye.github.io/atproto-mcp/api/tools/get-post-context.html): Gather surrounding context for a post (thread, author, engagement, media)

### Moderation
- [Report Content](https://cameronrye.github.io/atproto-mcp/api/tools/report-content.html): Report inappropriate content
- [Report User](https://cameronrye.github.io/atproto-mcp/api/tools/report-user.html): Report users
- [Analyze Moderation Status](https://cameronrye.github.io/atproto-mcp/api/tools/analyze-moderation-status.html): Inspect moderation labels/status for content or a user

### Lists Management
- [Create List](https://cameronrye.github.io/atproto-mcp/api/tools/create-list.html): Create user lists
- [Add to List](https://cameronrye.github.io/atproto-mcp/api/tools/add-to-list.html): Add users to lists
- [Remove from List](https://cameronrye.github.io/atproto-mcp/api/tools/remove-from-list.html): Remove users from lists
- [Get List](https://cameronrye.github.io/atproto-mcp/api/tools/get-list.html): Retrieve list information

### Resources
Three static resources are registered; all require authentication. The placeholder `atproto://conversation-context` resource from earlier releases has been removed.
- [Timeline Resource](https://cameronrye.github.io/atproto-mcp/api/resources/timeline.html): `atproto://timeline` — authenticated timeline data
- [Profile Resource](https://cameronrye.github.io/atproto-mcp/api/resources/profile.html): `atproto://profile` — authenticated profile data
- [Notifications Resource](https://cameronrye.github.io/atproto-mcp/api/resources/notifications.html): `atproto://notifications` — authenticated notification data

Two parameterized resource templates are also advertised (resources/templates/list); they expose any actor's public data and work without authentication:
- `atproto://profile/{actor}` — public profile for a handle or DID
- `atproto://feed/{actor}` — recent public posts by a handle or DID

Reading a URI that matches neither a static resource nor a template returns JSON-RPC error -32002 (Resource not found). The `{actor}` template variable supports completion/complete.

### Prompts
Two prompts are available; they are pure text templates and work without authentication:
- `content_composition` (args: `topic`, `tone`, `length`, `include_hashtags`)
- `reply_template` (args: `original_post`, `reply_type`, `relationship`)

Prompt arguments support completion/complete: enumerable arguments return candidate values; free-text arguments complete to an empty list.

### Types
- [Core Types](https://cameronrye.github.io/atproto-mcp/api/types/core.html): Core type definitions
- [Configuration Types](https://cameronrye.github.io/atproto-mcp/api/types/configuration.html): Configuration type definitions
- [Parameter Types](https://cameronrye.github.io/atproto-mcp/api/types/parameters.html): Parameter type definitions
- [Error Types](https://cameronrye.github.io/atproto-mcp/api/types/errors.html): Error type definitions
- [Utility Types](https://cameronrye.github.io/atproto-mcp/api/types/utilities.html): Utility type definitions

## Examples

- [Basic Usage](https://cameronrye.github.io/atproto-mcp/examples/basic-usage.html): Simple examples to get started
- [Social Operations](https://cameronrye.github.io/atproto-mcp/examples/social-operations.html): Working with posts, likes, and follows
- [Content Management](https://cameronrye.github.io/atproto-mcp/examples/content-management.html): Managing images, videos, and rich content
- [Custom Integration](https://cameronrye.github.io/atproto-mcp/examples/custom-integration.html): Building custom integrations

## Diagrams

- [Architecture](https://cameronrye.github.io/atproto-mcp/diagrams/architecture.html): System architecture diagrams

## Optional

- [Experimental & Roadmap](https://cameronrye.github.io/atproto-mcp/guide/experimental.html): OAuth login and other planned features (and why streaming is not planned)
- [Deployment Guide](https://cameronrye.github.io/atproto-mcp/guide/deployment.html): Deploy the server to production
- [Troubleshooting](https://cameronrye.github.io/atproto-mcp/guide/troubleshooting.html): Common issues and solutions
- [FAQ](https://cameronrye.github.io/atproto-mcp/FAQ.html): Frequently asked questions
- [Changelog](https://cameronrye.github.io/atproto-mcp/changelog.html): Version history and updates
- [Contributing](https://cameronrye.github.io/atproto-mcp/contributing.html): How to contribute to the project

