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

Run as a local MCP service

Use Streamable HTTP when several local agents should share one warmed knowledge base instead of each starting its own stdio server:

uv run atproto-mcp --streamable-http

The service accepts Streamable HTTP MCP connections at http://127.0.0.1:8000/mcp. It listens only on loopback and has no authentication, so it is not exposed to the local network. Configure each agent's Streamable HTTP MCP connection to use that URL. Choose another local port with uv run atproto-mcp --streamable-http --port 8787.

Start the local service on Linux login

The following user service starts after you log in. It runs under your account, needs no root access, and stops after your last login session ends.

# ~/.config/systemd/user/atproto-mcp.service
[Unit]
Description=AT Protocol MCP local service

[Service]
ExecStart=%h/.local/bin/uvx atproto-mcp --streamable-http
Restart=on-failure

[Install]
WantedBy=default.target

Create the directory, save the unit, then enable it for your user account:

mkdir -p ~/.config/systemd/user
systemctl --user daemon-reload
systemctl --user enable --now atproto-mcp.service

Check the service with systemctl --user status atproto-mcp.service. If uvx is installed elsewhere, replace %h/.local/bin/uvx in ExecStart with the path from command -v uvx. This setup starts on login only; it does not use sudo, a system service, or persistent login sessions.

Configuration

Claude Desktop (MCPB bundle) — recommended

Download atproto-mcp-<version>.mcpb from the latest release and open it. Claude Desktop shows an install dialog with optional fields for the cache directory, refresh interval, and embedding model; leave them blank for the defaults. No Python or JSON editing required — the host installs dependencies with uv.

Bundles are self-signed, so the installer shows an "unknown publisher" warning. See Releases for what that does and does not guarantee.

Every other host below uses the PyPI package and is unaffected by the bundle.

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 (manual)

Prefer the MCPB bundle above. To configure by hand instead, 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

The server connects immediately and warms up in the background, so a slow first run never blocks the host's startup handshake.

On first launch, warmup:

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

This takes a few minutes. Until it finishes, tools return a short message describing what the server is doing rather than failing. If warmup fails — no network yet, for example — the server stays up, says so, and retries on its own with exponential backoff until an index is in service. refresh_sources forces a retry immediately.

On subsequent launches the cached index is loaded and put into service before any network access, so queries work within seconds even offline. Repos older than 24 hours are then refreshed with a shallow fetch and a hard reset to the tracked branch. If the refreshed repos differ from what the index was built from, the existing 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

# Run a shared local MCP service at http://127.0.0.1:8000/mcp
uv run atproto-mcp --streamable-http

# 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

# Run the test suite (what CI runs)
uv run python -m unittest discover -s tests -p 'test*.py'

# Build the MCPB bundle
npm install -g @anthropic-ai/mcpb
mcpb validate .
mcpb pack . /tmp/atproto-mcp.mcpb

License

MIT