<div align="center"> <img src="docs/public/logo.svg" alt="AT Protocol MCP Server Logo" width="200" height="200">

AT Protocol MCP Server

</div>

A comprehensive Model Context Protocol (MCP) server that provides LLMs with direct access to the AT Protocol ecosystem, enabling seamless interaction with Bluesky and other AT Protocol-based social networks.

Supports both authenticated and unauthenticated modes - Start immediately with public data access (view profiles, search accounts, fetch follower/following lists), or add authentication for full functionality (search, write operations, private data, feeds).

Zero-config launch: npx atproto-mcp runs the server in unauthenticated public-data mode — no credentials required.

Recent additions: Bluesky direct messages, private bookmarks, starter pack discovery, reply/quote controls on posts, parameterized MCP resource templates, and an optional Streamable HTTP transport (--transport http).

Architecture

This MCP server acts as a bridge between LLM clients and the AT Protocol ecosystem:

┌─────────────────┐
│      User       │  "Search for posts about AI"
└────────┬────────┘
         │ Natural Language
         ▼
┌─────────────────┐
│   LLM Client    │  (Claude Desktop, etc.)
│  (MCP Client)   │
└────────┬────────┘
         │ MCP Protocol (JSON-RPC 2.0)
         ▼
┌─────────────────┐
│   This Server   │  AT Protocol MCP Server
│  (MCP Server)   │  - Tools, Resources, Prompts
└────────┬────────┘
         │ AT Protocol API
         ▼
┌─────────────────┐
│  AT Protocol    │  Bluesky, Custom PDS, etc.
│   Ecosystem     │
└─────────────────┘

Key Point: Users don't interact with this server directly. Instead, they talk to their LLM client in natural language, and the LLM client uses this MCP server to access AT Protocol functionality.

Features

Highlights

• Batch Operations: Perform multiple operations in a single call (follow/like/repost up to 25 items at once)
• Analytics & Insights: Analyze engagement patterns, network connections, and get content strategy recommendations
• Content Discovery: Find similar users, trending topics, starter packs, and influential voices in your areas of interest
• Direct Messages: List conversations, read message history, and send Bluesky DMs (requires a DM-enabled app password)
• Private Bookmarks: Save, list, and remove private bookmarks on posts

Core Features

• Zero-config Unauthenticated Mode: Run npx atproto-mcp to access public data without any setup - view profiles, search accounts, and fetch follower/following lists
• Optional Authentication: Enable full functionality with app passwords for write operations, feeds, and private data
• Complete AT Protocol Integration: Full implementation using official @atproto/api
• MCP Server Compliance: Built with @modelcontextprotocol/sdk following MCP specification
• Type-Safe: Written in TypeScript with strict type checking
• Comprehensive Tools: 51 MCP tools for social networking operations
• Rate Limiting: Built-in respect for AT Protocol rate limits
• Extensible: Modular architecture for easy customization

Planned: OAuth login is on the roadmap but not yet functional — app-password authentication is the supported auth path today. Real-time firehose streaming is not planned as MCP tools: a request/response tool cannot honestly expose a continuous stream, and the unused firehose client code has been removed. If streaming ever ships it will be built fresh on Jetstream.

Who Is This For?

Primary Audience: LLM Clients

This is an MCP (Model Context Protocol) server designed to be consumed by LLM clients such as:

• Claude Desktop
• Other MCP-compatible AI assistants
• Custom LLM applications using the MCP SDK

How it works:

User → LLM Client (Claude Desktop) → MCP Protocol → This Server → AT Protocol → Bluesky

Users interact with their LLM client in natural language (e.g., "search for posts about AI"), and the LLM client uses this MCP server to fulfill those requests by calling the appropriate tools via the MCP protocol.

Secondary Audience: Developers

This project is also for developers who want to:

• Deploy the MCP server for their LLM clients to connect to
• Extend the server with custom MCP tools and resources
• Contribute to the open-source project

This Is NOT:

• A direct-use REST API or SDK for application developers
• A JavaScript/TypeScript library to import into your app
• An end-user application

If you're building an application that needs AT Protocol functionality, you should either:

1. Use the official @atproto/api package directly, OR
2. Build an LLM-powered application that uses this MCP server through an LLM client

Installation

Run it with no install and no configuration — npx atproto-mcp launches the server in unauthenticated public-data mode immediately:

npx atproto-mcp

Or install globally:

npm install -g atproto-mcp

Claude Desktop

Add this to your Claude Desktop MCP configuration to run the server with zero config:

{
  "mcpServers": {
    "atproto": { "command": "npx", "args": ["-y", "atproto-mcp"] }
  }
}

Quick Start

Option 1: Unauthenticated Mode (Recommended for most use cases)

Perfect for LLM clients that need to access public AT Protocol data:

1. Configure your LLM client (e.g., Claude Desktop) to launch the MCP server:

   Add to your LLM client's MCP configuration:

   {
     "mcpServers": {
       "atproto": {
         "command": "npx",
         "args": ["atproto-mcp"]
       }
     }
   }
   

2. Start your LLM client - it will automatically launch the MCP server

3. Interact in natural language - Ask your LLM to search posts, view profiles, etc.

What your LLM can do in unauthenticated mode:

• View user profiles (get_user_profile - works without auth, provides additional viewer-specific data when authenticated)
• Search for accounts by handle or name (search_actors)
• List a user's posts (get_author_feed)
• View follower/following lists (get_user_connections with direction: 'followers' | 'follows' - ENHANCED mode: works without auth, enriches the underlying API call when authenticated)

Note: The following features require authentication:

• Searching posts and hashtags (search_posts) - API changed in 2025 to require authentication
• Browsing feeds and threads (get_post_context, get_custom_feed, get_timeline)
• All write operations (create, like, repost, follow, etc.)
• Resources (timeline, profile, notifications) - these are listed but require authentication to return data

Prompts (content composition, reply templates) are pure text templates and work without authentication.

Important: All tools, resources, and prompts are listed by the MCP server regardless of authentication state. Most tools and resources that require authentication will return a clear error message when called without proper credentials.

Option 2: Authenticated Mode (For full functionality)

Enable write operations and private data access for your LLM:

1. Configure your LLM client with AT Protocol credentials:

   {
     "mcpServers": {
       "atproto": {
         "command": "npx",
         "args": ["atproto-mcp"],
         "env": {
           "ATPROTO_IDENTIFIER": "your-handle.bsky.social",
           "ATPROTO_PASSWORD": "your-app-password"
         }
       }
     }
   }
   

2. Start your LLM client - it will launch the authenticated MCP server

What your LLM can do in authenticated mode:

• Create, edit, and delete posts
• Follow/unfollow users
• Like and repost content
• Access personalized timelines and notifications
• Manage lists and moderation settings

Available Tools

The server provides 51 MCP tools across multiple categories. See the complete API documentation for detailed information on each tool.

Public Tools (No Authentication Required)

Data Retrieval

• get_user_profile - Retrieve basic user information (ENHANCED mode: works without auth, provides additional viewer-specific data when authenticated)
• get_user_summary - Get a profile with recent posts and engagement stats in one call (ENHANCED mode)
• search_actors - Find accounts by handle or display name (ENHANCED mode)
• get_author_feed - List a specific user's posts (ENHANCED mode)
• get_user_connections - Get follower or following lists via direction: 'followers' | 'follows' (ENHANCED mode: works without auth, enriches the underlying API call when authenticated)
• get_post_context - Get a post with optional thread, author profile, engagement metrics, and media (ENHANCED mode)
• search_starter_packs / get_starter_pack - Search Bluesky starter packs by keyword and fetch a pack's details (ENHANCED mode)

Rich Media

• analyze_image - Report blob-declared size and MIME type for an image (PUBLIC mode: no auth required; does not decode pixels, so no dimensions/aspect ratio)

Note: As of 2025, the AT Protocol API has changed to require authentication for most endpoints that were previously public, including search_posts.

Private Tools (Authentication Required)

Social Operations

• create_post - Create posts with text, auto-detected or explicit richtext facets, replies, image/external embeds, and quote posts
• create_thread - Create multi-post threads in one call
• reply_to_post - Reply to existing posts with threading
• like_post / unlike_post - Like and unlike posts
• repost / unrepost - Repost content with optional quotes
• follow_user / `unfollow_us