Skip to main content
Glama

atproto-mcp

Tests

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

Related MCP server: Cardano Unified MCP Server

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

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

Install in VS Code

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

Available Tools

8 tools
get_cookbook_exampleA

Retrieve a specific AT Protocol cookbook example by project name.

Returns the project README, file listing, and key source code files. Use this when you need implementation examples or starter code.

Args: name: Project directory name (e.g. "python-bsky-post", "ts-bot", "go-repo-export", "python-oauth-web-app"). Use list_cookbook_examples to discover available projects.

Inputs: name (required). Returns: result

get_lexiconA

Retrieve a specific AT Protocol lexicon by its NSID.

Returns the full lexicon schema including type definitions, properties, descriptions, and cross-references. Use this when you need the complete definition of a specific endpoint or record type.

Args: nsid: The Namespaced Identifier (e.g. "app.bsky.feed.post", "com.atproto.repo.createRecord", "chat.bsky.convo.sendMessage").

Inputs: nsid (required). Returns: result

list_cookbook_examplesA

List all AT Protocol cookbook examples (starter projects and scripts).

Use this to discover available example projects before fetching specific ones with get_cookbook_example.

Args: language: Optional filter by language ("python", "go", "typescript", "javascript"). Leave empty to list all.

Inputs: language. Returns: result

list_lexiconsA

List all AT Protocol lexicons, optionally filtered by namespace prefix.

Use this to discover available lexicons and their NSIDs before fetching specific ones with get_lexicon.

Args: namespace: Optional namespace prefix to filter by (e.g. "app.bsky.feed", "com.atproto.repo", "chat.bsky", "tools.ozone"). Leave empty to list all.

Inputs: namespace. Returns: result

refresh_sourcesA

Force re-fetch all AT Protocol source repositories and rebuild the search index.

Use this when you suspect the documentation is outdated or when upstream repos have been updated. This operation may take several minutes as it clones repositories and rebuilds the embeddings index.

Inputs: no named parameters. Returns: result

search_atproto_docsA

Search across all AT Protocol documentation, lexicons, Bluesky API docs, and cookbook examples.

Use this tool to find information about AT Protocol concepts, endpoints, data structures, authentication, federation, and implementation patterns. Search is hybrid (keyword + semantic), so exact identifiers like NSIDs ("app.bsky.feed.getFeed") or endpoint names match reliably.

Args: query: Natural language search query (e.g. "how to create a post", "OAuth authentication flow", "what is a DID"). source: Optional filter — restrict to a specific source: "atproto-website" (protocol specs/guides from atproto.com), "bsky-docs" (Bluesky API docs from docs.bsky.app), "lexicons" (AT Protocol lexicon schemas), "cookbook" (example projects and code). Leave empty to search all sources. content_type: Optional filter — restrict to a content type: "guide" (tutorials and how-to guides), "spec" (protocol specifications), "blog" (blog posts), "reference" (lexicon schemas and API references), "example" (cookbook examples and code). Leave empty to search all types. limit: Maximum number of results (1-20, default 10).

Inputs: query (required), limit, source, content_type. Returns: result

search_bsky_apiA

Search Bluesky developer API documentation (docs.bsky.app).

Searches guides, tutorials, and advanced topics specific to the Bluesky API. Use this for questions about Bluesky-specific features like the firehose, federation, moderation, or API usage patterns.

Args: query: Search query (e.g. "firehose subscription", "custom feeds", "authentication", "rate limits"). limit: Maximum results (1-20, default 10).

Inputs: query (required), limit. Returns: result

search_lexiconsA

Search within AT Protocol lexicons using semantic search.

Searches lexicon descriptions, property names, types, and definitions. More targeted than search_atproto_docs when you specifically need lexicon/schema information.

Args: query: Search query (e.g. "post creation", "follow relationship", "blob upload", "moderation labels"). limit: Maximum results (1-20, default 10).

Inputs: query (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools are mostly distinct with clear list/get pairs for cookbook examples and lexicons, plus three search tools with different scopes. However, search_atproto_docs can be filtered to mimic search_lexicons and search_bsky_api, creating minor potential for misselection.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern using 'list', 'get', 'search', and 'refresh'. The naming clearly signals the action and the resource, making it predictable and easy to understand.

    Tool Count5/5

    With 8 tools, the server is well-scoped for a documentation and examples service. Each tool serves a clear purpose without unnecessary overlap or bloat, falling comfortably within the ideal 3-15 tool range.

    Completeness4/5

    The server covers the core needs for exploring AT Protocol docs: listing and fetching lexicons, listing and fetching cookbook examples, and searching across multiple sources. A minor gap is the lack of a direct way to retrieve a specific documentation page by URL, but the search tools likely handle most use cases.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers