# atproto-mcp [![Tests](https://github.com/Ashex/atproto-mcp/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Ashex/atproto-mcp/actions/workflows/tests.yml) MCP server providing a searchable knowledge base for the [AT Protocol](https://atproto.com/) ecosystem — protocol documentation, lexicon schemas, Bluesky developer API docs, and cookbook examples — powered by [txtai](https://github.com/neuml/txtai) semantic search. ## Data Sources | Source | Repository | Description | | -------- | ----------- | ------------- | | **AT Protocol Website** | [bluesky-social/atproto-website](https://github.com/bluesky-social/atproto-website) | Protocol specs, guides, and blog posts from atproto.com | | **Bluesky API Docs** | [bluesky-social/bsky-docs](https://github.com/bluesky-social/bsky-docs) | Developer docs from docs.bsky.app — tutorials, guides, advanced topics | | **AT Protocol Lexicons** | [bluesky-social/atproto](https://github.com/bluesky-social/atproto/tree/main/lexicons) | JSON schemas defining all AT Protocol endpoints and record types | | **Cookbook** | [bluesky-social/cookbook](https://github.com/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](https://docs.astral.sh/uv/) (recommended) or pip - Git (for cloning source repositories) ### Install from source ```bash git clone https://github.com/Ashex/atproto-mcp.git cd atproto-mcp uv sync ``` ### Run with uvx ```bash 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: ```bash 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. ```ini # ~/.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: ```bash 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-.mcpb` from the [latest release](https://github.com/Ashex/atproto-mcp/releases/latest) 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](#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](https://img.shields.io/badge/VS_Code-Install_ATproto_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22atproto-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22atproto-mcp%22%5D%7D) Add to `.vscode/mcp.json` in your workspace: ```json { "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](#claude-desktop-mcpb-bundle--recommended) above. To configure by hand instead, add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "atproto": { "command": "uvx", "args": [ "atproto-mcp" ] } } } ``` ### MCPHub Add to `~/.config/mcphub/servers.json`: ```json { "mcpServers": { "atproto": { "command": "uvx", "args": ["atproto-mcp"] } } } ``` ### OpenCode Add to your `opencode.json`: ```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 ```bash # 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