atproto-mcp

MCP server providing a searchable knowledge base for the AT Protocol ecosystem — protocol documentation, lexicon schemas, Bluesky developer API docs, and cookbook examples — powered by txtai semantic search.

Data Sources

Source	Repository	Description
AT Protocol Website	bluesky-social/atproto-website	Protocol specs, guides, and blog posts from atproto.com
Bluesky API Docs	bluesky-social/bsky-docs	Developer docs from docs.bsky.app — tutorials, guides, advanced topics
AT Protocol Lexicons	bluesky-social/atproto	JSON schemas defining all AT Protocol endpoints and record types
Cookbook	bluesky-social/cookbook	Example projects in Python, Go, TypeScript, and JavaScript

Tools

Tool	Description
search_atproto_docs	Semantic search across all documentation sources
get_lexicon	Retrieve a specific lexicon by NSID (e.g. app.bsky.feed.post)
list_lexicons	List all lexicons, optionally filtered by namespace
search_lexicons	Semantic search within lexicon schemas
get_cookbook_example	Get a specific cookbook example by project name
list_cookbook_examples	List all cookbook examples, optionally by language
search_bsky_api	Semantic search within Bluesky API docs
refresh_sources	Force re-fetch repos and rebuild the index

Prompts

Prompt	Description
explain_lexicon	Get a comprehensive explanation of a lexicon
implement_feature	Get implementation guidance with code examples
debug_atproto	Help debug AT Protocol / Bluesky API issues
explore_namespace	Explore all lexicons in a namespace

Installation

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• Git (for cloning source repositories)

Install from source

git clone https://github.com/ashex/atproto-mcp.git
cd atproto-mcp
uv sync

Run with uvx

uvx atproto-mcp

Configuration

VS Code / Copilot

Add to .vscode/mcp.json in your workspace:

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

Kiro Power

1. Open Kiro → Powers
2. Select Import power from GitHub
3. Enter https://github.com/ashex/atproto-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

MCPHub

Add to ~/.config/mcphub/servers.json:

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

OpenCode

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atproto": {
      "type": "local",
      "command": ["uvx", "atproto-mcp"]
    }
  }
}

Environment Variables

Variable	Default	Description
ATPROTO_MCP_CACHE_DIR	~/.cache/atproto-mcp	Where repos and the search index are stored
ATPROTO_MCP_REFRESH_HOURS	24	Hours before re-fetching repositories
ATPROTO_MCP_EMBEDDING_MODEL	sentence-transformers/all-MiniLM-L6-v2	Sentence-transformers model for embeddings

How It Works

On first launch, the server:

1. Shallow clones the repos into ~/.cache/atproto-mcp/repos/
2. Parses MDX docs, lexicon schemas, and cookbook examples into text chunks
3. Indexes the chunks using txtai with the all-MiniLM-L6-v2 sentence-transformer model (~80MB, runs locally)
4. Index is persisted in ~/.cache/atproto-mcp/index/ for subsequent starts

On subsequent launches, the cached index loads in seconds. Repos older than 24 hours are automatically refreshed with git pull.

Development

# Install in development mode
uv sync

# Run the server locally (stdio)
uv run atproto-mcp

# Test with the MCP Inspector
uv run mcp dev src/atproto_mcp/server.py

# Run with debug logging
ATPROTO_MCP_CACHE_DIR=/tmp/atproto-mcp uv run atproto-mcp

License

MIT