atproto-mcp
Use this MCP server as a searchable AT Protocol knowledge base for docs, lexicons, Bluesky API docs, and cookbook examples.
Search across all AT Protocol documentation, lexicons, Bluesky API docs, and cookbook examples.
Retrieve a specific lexicon by NSID.
List lexicons, optionally filtered by namespace.
Semantically search lexicon schemas.
Retrieve or list cookbook examples, optionally filtered by language.
Search Bluesky developer API documentation.
Force re-fetching of source repositories and rebuilding of the search index.
Provides semantic search and access to AT Protocol/Bluesky documentation, lexicon schemas, and cookbook examples. Tools include search, lexicon retrieval, and cookbook example lookup.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@atproto-mcp search for creating a post in AT Protocol"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | Protocol specs, guides, and blog posts from atproto.com | |
Bluesky API Docs | Developer docs from docs.bsky.app — tutorials, guides, advanced topics | |
AT Protocol Lexicons | JSON schemas defining all AT Protocol endpoints and record types | |
Cookbook | Example projects in Python, Go, TypeScript, and JavaScript |
Related MCP server: Cardano Unified MCP Server
Tools
Tool | Description |
| Semantic search across all documentation sources |
| Retrieve a specific lexicon by NSID (e.g. |
| List all lexicons, optionally filtered by namespace |
| Semantic search within lexicon schemas |
| Get a specific cookbook example by project name |
| List all cookbook examples, optionally by language |
| Semantic search within Bluesky API docs |
| Force re-fetch repos and rebuild the index |
Prompts
Prompt | Description |
| Get a comprehensive explanation of a lexicon |
| Get implementation guidance with code examples |
| Help debug AT Protocol / Bluesky API issues |
| 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 syncRun with uvx
uvx atproto-mcpRun 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-httpThe 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.targetCreate 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.serviceCheck 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
Open Kiro → Powers
Select Import power from GitHub
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 |
|
| Where repos and the search index are stored |
|
| Hours before re-fetching repositories |
|
| 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:
Shallow clones the repos into
~/.cache/atproto-mcp/repos/Parses MDX docs, lexicon schemas, and cookbook examples into text chunks
Indexes the chunks using txtai hybrid search (BM25 keyword + dense vectors from the
bge-small-en-v1.5sentence-transformer, ~130MB, runs locally) — exact identifiers like NSIDs match reliably alongside semantic queriesIndex 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.mcpbLicense
MIT
Available Tools
8 toolsget_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Official MCP server for twitterapis.com. Twitter/X search, users, DMs, Grok, monitoring and writes.
MCP server for querying Forkast documentation
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
MCP server for accessing curated awesome list documentation
Related MCP Servers
- AlicenseAqualityDmaintenanceA remote MCP server providing a tool for searching and querying ATprotocol documentation, helping developers easily access information while building on the protocol.117Creative Commons Zero v1.0 Universal
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides AI assistants with searchable access to Cardano ecosystem documentation, SDKs, smart contract languages, governance, scaling, and developer standards from a single endpoint.3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server that enables AI agents to search, fetch, and analyze a self-maintaining markdown knowledge base with provenance, drift detection, and canonical definitions.1MIT
- FlicenseNot gradedqualityBmaintenanceMCP server for a content-first knowledge base, enabling AI agents to search (full-text, semantic, hybrid) and retrieve Markdown documents, list content, and find related docs.-