atproto-mcp

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.12+
• 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 | BAAI/bge-small-en-v1.5 | 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 hybrid search (BM25 keyword + dense vectors from the bge-small-en-v1.5 sentence-transformer, ~130MB, runs locally) — exact identifiers like NSIDs match reliably alongside semantic queries
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. If the refreshed repos differ from what the index was built from, the stale index keeps serving queries while a fresh one is rebuilt in the background and swapped in when ready.

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