# Atproto Mcp

> A MCP server that gives LLMs direct access to the AT Protocol ecosystem, enabling seamless interaction with Bluesky and other AT Protocol-based social networks.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cameronrye-atproto-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cameronrye](https://agentstack.voostack.com/s/cameronrye)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cameronrye](https://github.com/cameronrye)
- **Source:** https://github.com/cameronrye/atproto-mcp
- **Website:** https://cameronrye.github.io/atproto-mcp/

## Install

```sh
agentstack add mcp-cameronrye-atproto-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AT Protocol MCP Server

[](https://badge.fury.io/js/atproto-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)

[](https://github.com/cameronrye/atproto-mcp/actions/workflows/ci.yml)
[](https://github.com/cameronrye/atproto-mcp/actions/workflows/integration-tests.yml)
[](https://github.com/cameronrye/atproto-mcp/actions/workflows/docs.yml)
[](https://github.com/cameronrye/atproto-mcp/actions/workflows/release.yml)
[](https://codecov.io/gh/cameronrye/atproto-mcp)

[](https://cameronrye.github.io/atproto-mcp)
[](SECURITY.md)

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](https://docs.bsky.app/blog/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:

```bash
npx atproto-mcp
```

Or install globally:

```bash
npm install -g atproto-mcp
```

### Claude Desktop

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

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

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

   ```json
   {
     "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](https://cameronrye.github.io/atproto-mcp/api/) 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_user` - Follow and unfollow users

**Data Retrieval**

- `search_posts` - Search for posts and content across the network (⚠️ API
  changed in 2025 to require auth)
- `get_custom_feed` - Access custom feeds
- `get_timeline` - Retrieve personalized timelines
- `get_notifications` - Access notification feeds (use `countOnly: true` for a
  cheap unread badge count)
- `mark_notifications_seen` - Mark notifications as seen up to a timestamp

**Direct Messages**

- `list_conversations` - List your Bluesky DM conversations
- `get_conversation_messages` - Read a conversation's message history
- `send_direct_message` - Send a DM (requires an app password created with
  "Allow access to your direct messages" enabled)

**Bookmarks**

- `add_bookmark` / `remove_bookmark` - Privately bookmark and un-bookmark posts
- `get_bookmarks` - List your private bookmarks

**Content Management**

- `upload_image` / `upload_video` - Upload media content
- `delete_post` - Remove posts
- `update_profile` - Modify profile and settings
- `generate_link_preview` - Generate link previews for posts

**List Management**

- `create_list` - Create user lists
- `add_to_list` / `remove_from_list` - Manage list members
- `get_list` - Retrieve list information

**Moderation**

- `mute_user` / `unmute_user` - Mute and unmute users
- `block_user` / `unblock_user` - Block and unblock users
- `report_content` / `report_user` - Report content and users
- `analyze_moderation_status` - Check moderation status of content

**Batch Operations**

- `batch_action` - Apply one action across up to 25 targets in a single call via
  `action: 'follow' | 'like' | 'repost'`

**Analytics & Insights**

- `analyze_account` - Analyze a single account along one dimension via
  `dimension: 'engagement' | 'network' | 'strategy'`
- `find_influential_users` - Find influential users in a topic area

**Content Discovery**

- `discover` - Surface timeline content via `mode: 'trending' | 'recommended'`
- `find_similar_users` - Find users similar to a given user
- `discover_communities` - Discover communities around topics

## Documentation

Visit our [documentation site](https://cameronrye.github.io/atproto-mcp) for:

- **Getting Started Guide**
- **API Reference**
- **Configuration Options**
- **Examples and Tutorials**
- **Troubleshooting**

## Authentication (Optional)

The server works perfectly without authentication for accessing public data.
Authentication is only needed for write operations and private data access.

### App Passwords (Recommended for Development)

```bash
export ATPROTO_IDENTIFIER="your-handle.bsky.social"
export ATPROTO_PASSWORD="your-app-password"
atproto-mcp
```

App passwords are the supported authentication path. OAuth login is planned but
not yet functional.

## Development

### Quick Start

```bash
# Clone the repository
git clone https://github.com/cameronrye/atproto-mcp.git
cd atproto-mcp

# Install dependencies (use pnpm, npm, or yarn)
pnpm install  # or: npm install

# Start development server
pnpm dev      # or: npm run dev

# Run tests
pnpm test     # or: npm test

# Build for production
pnpm build    # or: npm run build
```

### Available Commands

This project provides cross-platform npm scripts that work on Windows, macOS,
and Linux:

```bash
# Show all available commands
npm run help

# Development
npm run dev              # Start development server with hot reload
npm run build            # Build for production
npm run start            # Start production server

# Testing & Quality
npm test                 # Run tests
npm run test:coverage    # Run tests with coverage
npm run test:ui          # Run tests with interactive UI

# Integration Tests (connects to real AT Protocol servers)
npm run test:integration

npm run lint             # Run ESLint
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier
npm run type-check       # Run TypeScript type checking
npm run check            # Run all quality checks

# Utilities
npm run clean            # Clean build artifacts
npm run clean:all        # Clean everything including node_modules
npm run status           # Show project status
npm run ci               # Run full CI pipeline locally

# Dependencies
npm run deps:update      # Update dependencies
npm run deps:audit       # Audit for security issues
```

### Cross-Platform Compatibility

All build commands work on **Windows, macOS, and Linux** without requiring
additional tools. Simply use npm scripts on any platform (e.g., `npm run dev`,
`npm test`, `npm run build`).

## Testing

The project includes comprehensive test coverage:

### Unit Tests

```bash
# Run all unit tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run with interactive UI
pnpm test:ui
```

### Integration Tests

Comprehensive integration tests that connect to real AT Protocol servers to
validate all public-facing functionality:

```bash
# Run integration tests (requires internet connection)
npm run test:integration
```

**What's tested:**

- Public/enhanced tools (`get_user_profile`, `get_user_connections`,
  `get_author_feed`) and authenticated tools (`search_posts`,
  `get_post_context`, `get_custom_feed`)
- DID and handle resolution
- Pagination support
- Error handling
- AT Protocol specification compliance
- Rate limiting behavior

**Note:** Integration tests are opt-in and disabled by default to avoid hitting
real servers during normal development. See
[Integration Tests Documentation](src/__tests__/INTEGRATION_TESTS.md) for
details.

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md)
for details.

1. Fork the repository
2. Create a feature branch
3. Make

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cameronrye](https://github.com/cameronrye)
- **Source:** [cameronrye/atproto-mcp](https://github.com/cameronrye/atproto-mcp)
- **License:** MIT
- **Homepage:** https://cameronrye.github.io/atproto-mcp/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cameronrye-atproto-mcp
- Seller: https://agentstack.voostack.com/s/cameronrye
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.