outlineMcp

MCP文档知识

提供方 sinjinwoo

文档知识 stdio · 本地进程 OAuth 授权 社区 / 第三方 Claude DesktopClaudeCursorGemini CLI
查看接入方式

A RAG (Retrieval-Augmented Generation) + MCP (Model Context Protocol) server that automatically vectorizes documents in Outline wiki for AI agents to perform semantic natural-language search.

一句话选型结论

按资料字段整理

outlineMcp 属于文档知识类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

Local Deployment Semantic Search Vectorization Python AI Agents Document Processing RAG

支持客户端

适用场景

Local DeploymentSemantic SearchVectorization

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
https://mcp.your-domain.com/mcp

把它填进客户端的 MCP 配置即可,不需要在本地安装运行时。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
outlineMcp当前 未标注 stdio · 本地进程 本地部署 有 2026-07-08
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方sinjinwoo上游标注的维护方 sinjinwoo
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-07-08上游最后核验时间

详细介绍

17.0 KB
来自项目仓库与上游目录的原文,未做删改

🌐 Language: English | 한국어


🚀 Outline RAG MCP Server

A RAG (Retrieval-Augmented Generation) + MCP (Model Context Protocol) server that automatically vectorizes the documents in your Outline wiki, so AI agents (Claude Desktop, etc.) can run semantic natural-language search over them.

It shares your self-hosted Outline stack's existing Redis instead of spinning up its own, so it drops in with a single Docker Compose file and no wasted resources.


✨ Key Features

  • Single-container deployment (outline-mcp-vector): FastAPI, Celery (Worker/Beat), and the MCP server all run in one container, which keeps operations simple.
  • Infra-efficient: Reuses Outline's existing Redis container, isolated on its own logical DB (db/1) so the two queues never collide.
  • Smart incremental sync: Real-time webhooks and a periodic scheduler (hourly by default) work together, tracking only documents changed or deleted since the last updated_at cursor — no full re-embed on every run.
  • Gemini key pool: Register multiple Gemini API keys and they're called round-robin, with automatic failover when one hits a rate limit (429).
  • MCP auth is opt-in Keycloak/OAuth: the MCP server (Streamable HTTP) is fully open by default — set MCP_OAUTH_ENABLED=true (plus issuer/resource/audience) to require a Keycloak-issued Bearer JWT instead. This project only ever acts as an OAuth Resource Server; it doesn't run or provision Keycloak itself.

🛠 Architecture```text

Outline Stack (existing infra) outline-net (shared network)
┌──────────────────────────────┐ │
│ [Outline] [Redis] │◄─────────────┼──────────────┐
└───────────────────▲──────────┘ │ │
│ (reuses logical DB /1) │ │
┌───────────────────┴─────────────────────────▼──────────────┼
│ outline-mcp-vector (1 Container Stack) │
│ - FastAPI (receives webhooks, responds immediately) │
│ - Celery Worker & Beat (background chunking/embedding/sched)│
│ - MCP Server (serves the search_knowledge tool over Streamable HTTP) │
└─────────────────────────────────────────────┬──────────────┘
│ (rag-net)
┌──────▼───────────────────────┐
│ Qdrant (internal vector DB) │
└──────────────────────────────┘


---

## 📦 3-Minute Quick Start

### 1. Prep Outline and create a webhook

Before starting the RAG server, gather what you need from the Outline admin screen.

1. **Issue an API key**: In Outline, go to **Settings → API Tokens** and create a new token (`OUTLINE_API_KEY`).
2. **Register a webhook and grab its secret**: Go to **Settings → Webhooks → New webhook**, register it as below, and copy the **Secret** shown.
* **URL**: `http://:17000/webhook/outline` (the address the RAG server listens on)
* **Events**: select `documents.create`, `documents.update`, `documents.delete`
* *Keep the secret string shown after creation somewhere safe (`OUTLINE_WEBHOOK_SECRET`).*

### 2. Check Outline's Docker network

For the RAG server to reach the Outline and Redis containers over the internal network, your existing Outline `docker-compose.yml` needs an explicit external network name (`outline-net`).```yaml
# Add this to your existing Outline docker-compose.yml if it's missing, then restart Outline
services:
  outline:
    networks: [outline-net]
  redis:
    networks: [outline-net]

networks:
  outline-net:
    name: outline-net

3. Set environment variables (.env)

Create a .env file in your install directory and fill in the values from step 1 plus the required settings.```env

Outline integration (values gathered in step 1)

OUTLINE_API_KEY=ol_api_xxxxxxxxxxxx # Outline API token
OUTLINE_WEBHOOK_SECRET=your_secret_key # Secret copied from the Outline webhook screen
OUTLINE_API_URL=http://outline:3000 # Internal Docker-network URL
OUTLINE_PUBLIC_URL=https://wiki.domain.com # Public URL real users hit in their browser

AI and vector DB settings

GOOGLE_API_KEYS=key1,key2,key3 # Gemini API keys (comma-separated for a round-robin pool)
QDRANT__SERVICE__API_KEY=strong_qdrant_key # Any string you like, used to authenticate to Qdrant

DNS rebinding protection (Host/Origin header validation). Comma-separate your deployed

domain(s); leave unset to keep this off (pre-existing behavior). Only relevant against

malicious webpages attacking through a browser — non-browser clients (curl, Claude

Desktop's remote connector) don't send an Origin header and aren't affected either way.

MCP_ALLOWED_HOSTS=mcp.your-domain.com

MCP_ALLOWED_ORIGINS=https://mcp.your-domain.com

MCP auth — off by default (server is fully open). Set MCP_OAUTH_ENABLED=true and fill in

the rest to require a Keycloak-issued Bearer JWT instead. This server is a Resource Server

only; it validates against your Keycloak realm's JWKS, it doesn't run Keycloak itself

(see docs/keycloak-reference-compose.yml for a throwaway realm to test against).

MCP_OAUTH_ENABLED=true

MCP_OAUTH_ISSUER_URL=https://keycloak.your-domain.com/realms/myrealm

MCP_OAUTH_RESOURCE_URL=https://mcp.your-domain.com/mcp

MCP_OAUTH_AUDIENCE=outline-mcp-client


See the MCP spec's own Authorization guide for the OAuth concepts behind the `MCP_OAUTH_*` vars above (Resource Server vs Authorization Server, Protected Resource Metadata, etc).

| Variable | Required? | Default | Notes |
|---|---|---|---|
| `OUTLINE_API_KEY` | **Required** | — | Outline API token (Settings → API & Apps) |
| `OUTLINE_WEBHOOK_SECRET` | **Required** | — | Outline webhook signing secret. If left empty, webhook signature verification is skipped entirely — not recommended |
| `OUTLINE_BASE_URL` | **Required** | — | Outline's public URL; also the fallback for `OUTLINE_API_URL`/`OUTLINE_PUBLIC_URL` below |
| `GOOGLE_API_KEYS` | **Required**¹ | — | Comma-separated Gemini API key pool, round-robin with failover |
| `QDRANT__SERVICE__API_KEY` | **Required** | — | Any string; also passed to the Qdrant container itself as `service.api_key` |
| `GEMINI_API_KEY` | Optional | — | ¹ Single-key fallback if you don't need `GOOGLE_API_KEYS`' pool |
| `OUTLINE_API_URL` | Optional | = `OUTLINE_BASE_URL` | Internal Docker-network URL for actual Outline API calls |
| `OUTLINE_PUBLIC_URL` | Optional | = `OUTLINE_BASE_URL` | Public URL used to build the doc links shown in search results |
| `GEMINI_EMBEDDING_DIM` | Optional | `3072` | Output vector dimensionality |
| `GEMINI_TIMEOUT_MS` | Optional | `30000` | Per-request Gemini timeout, milliseconds |
| `QDRANT_URL` | Optional | `http://localhost:6333` | |
| `QDRANT_TIMEOUT_SECONDS` | Optional | `10` | Per-request Qdrant timeout, seconds |
| `MCP_HOST` | Optional | `0.0.0.0` | |
| `MCP_PORT` | Optional | `8080` | |
| `MCP_ALLOWED_HOSTS` | Optional | *(empty → protection off)* | Comma-separated Host allow-list for DNS rebinding protection |
| `MCP_ALLOWED_ORIGINS` | Optional | *(empty)* | Comma-separated Origin allow-list, same protection |
| `MCP_OAUTH_ENABLED` | Optional | `false` | Turns on Keycloak/OAuth Bearer-token auth; server is fully open while `false` |
| `MCP_OAUTH_ISSUER_URL` | Required if `MCP_OAUTH_ENABLED=true` | — | Keycloak realm issuer URL |
| `MCP_OAUTH_RESOURCE_URL` | Required if `MCP_OAUTH_ENABLED=true` | — | This server's own external URL, including the `/mcp` path |
| `MCP_OAUTH_AUDIENCE` | Required if `MCP_OAUTH_ENABLED=true` | — | Must match the `aud` claim your Keycloak client issues |
| `MCP_OAUTH_JWKS_URL` | Optional | `{issuer}/protocol/openid-connect/certs` | Only needed if your IdP doesn't use Keycloak's default path |
| `REDIS_URL` | Optional | `redis://redis:6379/1` | Shares Outline's Redis container, logical DB 1 |
| `SYNC_INTERVAL_SECONDS` | Optional | `3600` | Celery Beat's incremental-sync interval |

**Setting up the Keycloak client for `MCP_OAUTH_*`:** in the Keycloak admin console, on the realm you're pointing `MCP_OAUTH_ISSUER_URL` at —

1. A brand-new realm has no users of its own — the realm-creation wizard doesn't ask for one, and the `master` realm's admin account you log into the console with does **not** carry over. If anyone will ever log in interactively against this realm (e.g. Claude's browser-based OAuth flow, as opposed to a pure machine-to-machine `client_credentials` setup), create a real user first: **Users** → **Create new user**, then that user's **Credentials** tab → **Set password**.
2. **Clients** → **Create client** → give it a client ID (this is the same value you'll put in `MCP_OAUTH_AUDIENCE`). If this client will be used for a browser login flow, also enable **Standard flow** on its Settings tab, and add the caller's own OAuth callback to **Valid redirect URIs** (Claude's is `https://claude.ai/api/mcp/auth_callback`) — skip this and Keycloak lets the user log in successfully and only *then* rejects the redirect back, which looks like a login failure but isn't one.
3. Click into that client → **Client scopes** tab → open its `-dedicated` scope.
4. **Add mapper** → **By configuration** → **Audience**, then set **Included Client Audience** to that same client — this is what actually stamps the `aud` claim; without it, issued tokens carry Keycloak's default `aud` (`account`) instead, and every request fails signature-adjacent-but-audience-mismatch with a 401.
5. Save, then confirm it worked by decoding a freshly-issued token (e.g. at jwt.io) and checking `aud` actually contains your client ID — a mapper that got saved with an empty audience field silently adds nothing, which is easy to miss.

One more gotcha specific to `MCP_OAUTH_RESOURCE_URL`: it has to be an address the *client* can actually reach — if that client is Claude, it's running in Anthropic's cloud, not on your machine. Pointing this at `localhost` means the 401 response's `WWW-Authenticate` header advertises an unreachable metadata URL, so OAuth discovery silently fails. If you're tunnelling a local dev server (e.g. ngrok), this needs to be the tunnel's actual public HTTPS URL, and it changes every time a free-tier tunnel restarts. Also, if you're running this behind docker-compose, `docker compose restart` reuses the container's original environment and won't pick up an updated `.env` — use `docker compose up -d` to recreate it instead.

### 4. Run Docker Compose

Create a `docker-compose.yml` with the contents below and bring it up.```yaml
version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    expose:
      - "6333"
    environment:
      - QDRANT__SERVICE__API_KEY
    volumes:
      - qdrant_data:/qdrant/storage
    networks:
      - rag-net
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo -e \"GET /healthz HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n\" > /dev/tcp/localhost/6333' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5

  outline-mcp-vector:
    image: sjw0066/outline-mcp-vector:latest
    env_file: .env
    environment:
      - QDRANT_URL=http://qdrant:6333
      - REDIS_URL=redis://redis:6379/1 # Shares Outline's Redis container (logical DB 1)
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8080
    ports:
      - "17000:8000"   # FastAPI port (webhook, sync)
      - "17080:8080"   # FastMCP Streamable HTTP port
    volumes:
      - sync_state:/data
    networks:
      - rag-net
      - outline-net    # Joins Outline's existing network
    depends_on:
      qdrant:
        condition: service_healthy

networks:
  rag-net:
    driver: bridge
  outline-net:
    external: true     # References the already-running Outline network

volumes:
  qdrant_data:
  sync_state:

``````bash
docker compose up -d

> 💡 Note: Once the container is up, it detects that the Qdrant vector DB is empty and automatically pulls in all of Outline's existing documents for an initial full sync.


🔗 External Client Setup Guide (HTTPS / Streamable HTTP)

How to connect securely from a PC outside your home server, through an Nginx reverse proxy and an SSL certificate on your home server's domain.

1. Nginx reverse proxy config (required)

So the streaming responses FastMCP's Streamable HTTP transport uses don't get cut off, make sure your domain's proxy_pass block maps to the RAG server's port 17080 and disables proxy buffering.```nginx
server {
listen 443 ssl;
server_name mcp.your-domain.com;

ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;

location / {
    # ⭐ Key part: forward to the MCP port (17080) exposed by docker-compose.
    proxy_pass http://localhost:17080;

    # Required to keep the streaming connection alive in real time
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header Connection '';
    chunked_transfer_encoding off;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

}


### 2. Claude Desktop setup

By default (`MCP_OAUTH_ENABLED` unset) the MCP server processes any request with no auth check at all — fine behind a VPN/private network, but anyone who reaches the URL directly can search your knowledge base, so put it behind something (reverse-proxy IP allowlist, VPN, etc.) if it's reachable from the open internet. In that mode, just point Claude Desktop at the URL:```json
{
  "mcpServers": {
    "outline-knowledge-base": {
      "url": "https://mcp.your-domain.com/mcp"
    }
  }
}

If you turn on MCP_OAUTH_ENABLED=true (Keycloak), add the connector with Advanced settings → OAuth Client ID / OAuth Client Secret filled in with a Keycloak client's credentials, rather than leaving them blank. Claude Desktop can technically discover the server's OAuth metadata and attempt Dynamic Client Registration on its own, but Keycloak's default "Trusted Hosts" Client Registration Policy rejects anonymous DCR from hosts it doesn't already know about — in practice you need a pre-registered client either way, same as the Claude Code setup below (including registering Claude's callback, https://claude.ai/api/mcp/auth_callback, as a Valid redirect URI on that client). Once added with credentials, the first connection walks you through a normal browser login/consent flow — there's no static token to paste into the config. See docs/keycloak-reference-compose.yml for a throwaway Keycloak realm if you want to test this locally. Clients that can't run a browser-based OAuth flow can instead send an already-issued Keycloak access token directly as an Authorization: Bearer header.

3. Claude Code (CLI) setup

With OAuth off, add it like any other remote HTTP server:bash claude mcp add --transport http outline-knowledge-base https://mcp.your-domain.com/mcp

With MCP_OAUTH_ENABLED=true, skip Dynamic Client Registration and register a pre-configured client instead — Keycloak's default "Trusted Hosts" Client Registration Policy rejects anonymous DCR from hosts it doesn't already know about (a plain dev tunnel like ngrok will hit this), and Claude Code's own OAuth callback is a local loopback URL (http://localhost:PORT/callback), different from Claude Desktop's (https://claude.ai/api/mcp/auth_callback) — both need to be registered on the same Keycloak client if you use both.

  1. In Keycloak, add http://localhost:8080/callback (or whichever port you pick below) to that client's Valid redirect URIs, alongside any other client's callback already there.
  2. Register the server with that client's credentials:bash claude mcp add-json outline-knowledge-base \ '{"type":"http","url":"https://mcp.your-domain.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \ --client-secret
    (prompts for the secret; it's stored in your system keychain/credential store, not in .mcp.json)
  3. claude mcp login outline-knowledge-base (or /mcp inside a session) to run through the browser login.

⚙️ Manual Sync & Management API

For controlling indexing directly, beyond the background auto-sync (hourly by default).

  • Trigger an incremental sync: POST http://localhost:17000/sync/outline
  • Force a full re-index: POST http://localhost:17000/sync/outline?full=true
  • Check sync status: GET http://localhost:17000/sync/status

If this open-source project has been useful to you, please support it with a ⭐️ Star! Feel free to leave any questions in the Issues tab.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
outlineMcp 怎么安装?

在客户端按下面的安装命令接入:https://mcp.your-domain.com/mcp。装完在客户端配置里引用同一个包或端点。

outlineMcp 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

outlineMcp 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

outlineMcp 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

outlineMcp 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、Gemini CLI;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

outlineMcp 能提供哪些能力?

资料显示能力标签包括 Local Deployment、Semantic Search、Vectorization、Python、AI Agents、Document Processing。具体工具清单以官方文档为准。

outlineMcp 需要什么运行环境?

运行时为 python;属于本地进程,需要在本机装好运行环境。

outlineMcp 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-07-08。