outline-sync MCP server
Commit Nov 9, 2026Syncs documentation between Outline workspaces and local filesystems with bidirectional support and AI-powered semantic search.
Also known as kingston/outline-sync
- Stars
- 11
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is outline-sync MCP?
outline-sync syncs documentation between Outline workspaces and local filesystems with bidirectional support and AI-powered semantic search.
Summary generated from the project's README
About outline-sync MCP server
Synchronizing documentation between Outline workspaces and local filesystems is what this tool enables for developers and technical writers. It provides bidirectional support, allowing you to download documents to your machine as organized markdown files and upload local changes back to your Outline instance. This process maintains your existing hierarchy through nested folders and automatically handles embedded images by downloading them locally and restoring their URLs during uploads.
Users set up the server by providing an OUTLINE_API_TOKEN and a configuration file specifying target collections and an output directory. For advanced AI capabilities, you can configure providers like Anthropic, Google, or OpenAI. The tool includes specialized commands such as annotate to generate missing metadata and search to perform semantic queries across your collections. It is designed to work with static site generators like Astro Starlight and is optimized for AI assistants to read and interact with your documentation content.
What you can do with it
- 1Sync documentation for static sitesA developer can automate the process of pulling Outline docs into a local directory to build a website using Astro Starlight.
- 2Perform semantic documentation searchesYou can find specific information within your collections by searching for the meaning of a query rather than just keywords.
- 3Automate document metadata generationAn AI can scan your markdown files and automatically create titles and descriptions for documents that lack them.
- 4Update Outline from local editsAfter making improvements to your documentation locally, you can push those changes directly back to your Outline workspace.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ANTHROPIC_API_KEYGOOGLE_API_KEYOPENAI_API_KEYOUTLINE_API_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablekingston/outline-sync is public and reachablegithub.com/kingston/outline-sync ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/kingston/outline-sync ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHuboutline-sync
A tool for syncing documentation from Outline to your local filesystem, enabling seamless integration with static site generators and AI assistants.
Features
- 📥 Download documentation from Outline to your local filesystem
- 📤 Upload changes back to Outline
- 🎯 Selective sync with collection filtering
- 📁 Organized structure with nested folders matching your Outline hierarchy
- 🖼️ Image support - automatically download and upload embedded images
- 🤖 AI-friendly format for LLMs like Claude to read and interact with docs
- ⚡ Static site ready - works perfectly with Astro Starlight and other generators
- 🔄 Bidirectional sync - download from and upload to Outline
- 🔍 Semantic search - find documents using AI-powered similarity search
Installation
npm install outline-sync
# or
pnpm add outline-sync
# or
yarn add outline-sync
Configuration
Set your Outline API token as an environment variable:
# .env file or environment
OUTLINE_API_TOKEN=your-api-token-here
Create an outline-sync.config.js file in your project root:
export default {
// Optional: Outline API configuration
outline: {
// API URL (defaults to 'https://app.getoutline.com/api')
apiUrl: 'https://your-team.getoutline.com/api',
},
// Required: Collections to sync
collections: [
{
// The URL ID of the collection (from the collection's URL)
urlId: 'engineering-docs-h3kj5',
// Optional: Custom directory name (defaults to collection name)
directory: 'engineering',
},
{
urlId: 'api-reference-k2j8d',
},
],
// Optional: Output directory (defaults to 'docs')
outputDir: './docs',
// Optional: Behavior configuration
behavior: {
// Skip writing metadata files (defaults to false)
skipMetadata: false,
// Clean up removed documents after download (defaults to true)
cleanupAfterDownload: true,
// Download and upload embedded images (defaults to true)
includeImages: true,
},
// Optional: Language model configuration for AI features
languageModel: {
// Provider: 'anthropic', 'google', or 'openai'
provider: 'anthropic',
// Optional: Model name (defaults vary by provider)
model: 'claude-3-5-sonnet-20241022',
},
};
Usage
Command Line
# Download all documents from Outline
npx outline-sync download
# Upload local changes back to Outline
npx outline-sync upload
# Annotate documents with AI-generated titles/descriptions
npx outline-sync annotate
# Search across your Outline collections
npx outline-sync search "your search query"
# Use a custom config file
npx outline-sync download --config ./custom-config.js
Programmatic Usage
import { download, upload } from 'outline-sync';
// Download documents (uses config file and OUTLINE_API_TOKEN env var)
await download({
// Optional: Override output directory
dir: './custom-docs',
});
// Upload changes
await upload({
// Optional: Override source directory
source: './custom-docs',
// Optional: Target a specific collection
collection: 'engineering-docs-h3kj5',
// Optional: Only update existing documents
updateOnly: true,
});
Integration with Static Site Generators
Astro Starlight
Add outline-sync to your build process:
{
"scripts": {
"docs:sync": "outline-sync download",
"build": "npm run docs:sync && astro build"
}
}
Configure Starlight to read from the synced directory:
// astro.config.mjs
export default defineConfig({
integrations: [
starlight({
sidebar: [
{
label: 'Documentation',
autogenerate: { directory: 'docs' },
},
],
}),
],
});
AI Assistant Integration
The synced documentation structure is optimized for AI assistants like Claude to read and understand your documentation:
- Hierarchical structure - Collections become folders, maintaining your organization
- Markdown format - Clean, readable markdown files
- Metadata preservation - Document metadata is preserved in frontmatter
- Bidirectional updates - AI can suggest changes that can be uploaded back to Outline
Example workflow with Claude:
1. Sync docs: `npx outline-sync download`
2. Claude reads from `./docs` directory
3. Claude suggests documentation improvements
4. Upload changes: `npx outline-sync upload`
File Structure
After syncing, your documentation will be organized as:
docs/
├── collection-name/
│ ├── document-title.md
│ ├── document-title/
│ │ ├── 4fba1872-7f67-42ac-9d4b-5712197d0253.png
│ │ └── another-uuid.jpg
│ ├── nested-collection/
│ │ └── another-document.md
│ └── _metadata.json
└── another-collection/
└── document.md
Each markdown file includes:
- Frontmatter with document metadata (id, title, description)
- The document content in clean markdown
- Preserved formatting and structure
Image Support
When includeImages is enabled (default), outline-sync automatically handles embedded images:
Download
- Detects all images embedded in Outline documents
- Downloads images to a folder named after the document
- Converts Outline attachment URLs to relative paths in markdown
- Preserves image captions and alt text
Upload
- Detects relative image paths in your local markdown files
- Automatically uploads new images to Outline
- Restores existing Outline attachment URLs (based on UUID filenames)
- Handles image uploads for both new and existing documents
Example
Outline document with image:

Downloaded as:

The image file is saved to:
docs/collection-name/images/4fba1872-7f67-42ac-9d4b-5712197d0253.png
AI Features
Annotate Command
The annotate command uses AI to automatically generate titles and descriptions for your markdown documents that are missing this metadata. This is particularly useful after downloading documents from Outline that may not have complete frontmatter.
# Annotate all documents in all collections
npx outline-sync annotate
Language Model Support
The annotate command supports multiple language model providers. You'll need to:
-
Install the provider's package (optional peer dependencies):
# For Anthropic Claude npm install @langchain/anthropic # For Google Gemini npm install @langchain/google-genai # For OpenAI GPT npm install @langchain/openai -
Configure the provider in your config file:
export default { // ... other config languageModel: { provider: 'anthropic', // or 'google' or 'openai' model: 'claude-3-5-sonnet-20241022', // optional, defaults vary by provider }, }; -
Set the appropriate API key as an environment variable (see Environment Variables section)
The command will:
- Scan all markdown files in your configured collections
- Skip files that already have both title and description
- Use AI to generate appropriate titles and descriptions based on content
- Update the frontmatter while preserving all other metadata
Search Command
The search command enables semantic search across your Outline collections using vector embeddings:
# Search with default settings (5 results, no content)
npx outline-sync search "API authentication methods"
# Search with custom limit
npx outline-sync search "database optimization" --limit 10
# Include document contents in results
npx outline-sync search "error handling" --include-contents
# Search specific collections
npx outline-sync search "deployment process" --collections engineering-docs-h3kj5,devops-k2j8d
Features:
- Semantic search - Finds documents based on meaning, not just keywords
- Fast indexing - Creates vector embeddings for all documents
- Flexible results - Control result count and whether to include full content
- Collection filtering - Search across all collections or specific ones
Requirements:
- Requires language model configuration in your config file
- Automatically creates and manages search indexes using FAISS
Environment Variables
The tool requires the following environment variables:
# .env
# Required: Your Outline API token
OUTLINE_API_TOKEN=your-api-token-here
# Optional: API keys for language model providers (needed for annotate command)
ANTHROPIC_API_KEY=your-anthropic-key-here # For Anthropic Claude
GOOGLE_API_KEY=your-google-key-here # For Google Gemini
OPENAI_API_KEY=your-openai-key-here # For OpenAI GPT
API tokens are automatically loaded from the environment. You can use a .env file in your project root for local development.
API Token
To get your Outline API token:
- Log in to your Outline instance
- Go to Settings → API Tokens
- Create a new token with read/write permissions
- Copy the token and store it securely
Requirements
- Node.js 20+
- An Outline instance with API access
- API token with appropriate permissions
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT
Support
For issues and feature requests, please use the GitHub issue tracker.
outline-sync MCP questions
How do I sync my Outline documentation to my local machine?
You can download all documents from Outline by running the command npx outline-sync download.
Can I upload local changes back to my Outline workspace?
Yes, you can upload local changes back to Outline using the npx outline-sync upload command.
Does this tool support images?
Yes, it automatically downloads and uploads embedded images, converting Outline attachment URLs to relative paths in markdown.
How can I perform semantic search on my documents?
You can use the search command to find documents based on meaning using AI-powered similarity search.