msasikumar/outline-mcp-server

Outline MCP Server

A Model Context Protocol (MCP) server that integrates with your self-hosted Outline notes application at outline.sashi.online.

Features

This MCP server provides the following tools for interacting with Outline:

• outline_list_documents - List documents with optional filtering
• outline_search_documents - Search documents using natural language
• outline_get_document - Retrieve a specific document by ID
• outline_create_document - Create new documents in Markdown
• outline_update_document - Update existing documents
• outline_delete_document - Archive or permanently delete documents
• outline_list_collections - List all available collections

Prerequisites

• Docker and Docker Compose installed
• Outline API key from your Outline instance
• Access to outline.sashi.online

Getting Your Outline API Key

1. Log in to your Outline instance at https://outline.sashi.online
2. Go to Settings → API & Apps
3. Click Create Token or New API Key
4. Copy the generated API key (treat it like a password!)

Installation & Setup

Step 1: Navigate to the Project Directory

cd /Users/Sashi/outline-mcp-server

Step 2: Create Environment File

cp .env.example .env

Edit the .env file and add your Outline API key:

OUTLINE_URL=https://outline.sashi.online
OUTLINE_API_KEY=your_actual_api_key_here

Step 3: Build the Docker Image

docker-compose build

Step 4: Configure MCP Client

To use this server with Claude Desktop or other MCP clients, you need to configure it. The server communicates via stdio.

For Claude Desktop, add this to your MCP configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "outline": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/Users/Sashi/outline-mcp-server/.env",
        "outline-mcp-server"
      ]
    }
  }
}

Note: Make sure to build the image first with the tag:

docker build -t outline-mcp-server /Users/Sashi/outline-mcp-server

Usage

Running the Server Directly (for testing)

docker-compose up

Example Commands via MCP Client

Once configured with an MCP client like Claude Desktop, you can use natural language commands:

1. List all collections:

   • "Show me all my Outline collections"

2. Search for documents:

   • "Search for documents about Docker in Outline"

3. Create a new document:

   • "Create a new document titled 'Meeting Notes' in collection XYZ with content..."

4. Update a document:

   • "Update document ABC with new content..."

5. Get a specific document:

   • "Get the content of document with ID XYZ"

Tool Details

outline_list_collections

Lists all collections in your Outline workspace.

Parameters:

• limit (optional): Maximum number of collections (default: 25)

outline_list_documents

Lists documents from Outline.

Parameters:

• collectionId (optional): Filter by collection
• limit (optional): Maximum results (default: 25)
• offset (optional): Pagination offset (default: 0)

outline_search_documents

Search for documents using keywords or natural language.

Parameters:

• query (required): Search query
• collectionId (optional): Limit to specific collection
• limit (optional): Maximum results (default: 25)

outline_get_document

Get a specific document's content and metadata.

Parameters:

• id (required): Document UUID or URL ID

outline_create_document

Create a new document in Markdown format.

Parameters:

• title (required): Document title
• collectionId (required): Collection ID
• text (optional): Markdown content
• parentDocumentId (optional): For nested documents
• publish (optional): Publish immediately (default: false)

outline_update_document

Update an existing document.

Parameters:

• id (required): Document UUID
• title (optional): New title
• text (optional): New content
• append (optional): Append instead of replace (default: false)
• publish (optional): Publish document

outline_delete_document

Archive or permanently delete a document.

Parameters:

• id (required): Document UUID
• permanent (optional): Permanent delete vs archive (default: false)

Project Structure

outline-mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── Dockerfile            # Docker image configuration
├── docker-compose.yml    # Docker Compose setup
├── package.json          # Node.js dependencies
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variables template
└── README.md             # This file

Development

Local Development (without Docker)

1. Install dependencies:

npm install

2. Set environment variables:

export OUTLINE_URL=https://outline.sashi.online
export OUTLINE_API_KEY=your_api_key

3. Build:

npm run build

4. Run:

npm start

Watch Mode for Development

npm run dev

Troubleshooting

API Key Issues

If you get authentication errors:

• Verify your API key is correct in .env
• Check that the key hasn't expired
• Ensure you have permissions in Outline

Connection Issues

If the server can't connect to Outline:

• Verify outline.sashi.online is accessible
• Check your network/firewall settings
• Ensure HTTPS is working properly

Docker Issues

If Docker won't start:

• Ensure Docker daemon is running
• Check that the .env file exists and has the correct format
• Verify the image was built successfully

Security Notes

• Never commit your .env file or API keys to version control
• The API key has full access to your Outline account - protect it carefully
• Consider using Docker secrets for production deployments
• Regularly rotate your API keys

Contributing

Feel free to extend this server with additional Outline API endpoints:

• Document templates
• Share management
• Comments
• User management
• And more!

License

MIT

Support

For Outline API documentation, visit: https://www.getoutline.com/developers For MCP documentation, visit: https://modelcontextprotocol.io