outline-mcp

읽기 전용 MCP 서버로, Outline용입니다. 에이전트에게 위키에 대한 검색 및 읽기 액세스를 제공합니다 — 설계상 쓰기는 없습니다.

Why

Outline의 API는 평평한 RPC 표면입니다 — 모든 엔드포인트는 JSON 본문과 Bearer 토큰을 사용하는 POST {base}/api/<method>입니다. 이러한 균일성은 유용한 MCP 서버가 단일 요청 함수와 선별된 도구 목록으로 구성된다는 것을 의미합니다. 이 패키지는 의도적으로 작습니다: MCP SDK와 zod 외에는 런타임 의존성이 없으며, 에이전트가 올바른 도구를 선택하는지 결정하는 도구 설명과 출력 형식을 완전히 제어할 수 있습니다.

서버는 읽기 전용입니다: 코드 어디에도 생성, 업데이트, 이동 또는 보관 경로가 없습니다.

Related MCP server: outline-mcp

Tools

get_document는 전체 URL, 단순 urlId 또는 UUID를 허용합니다. urlId는 [A-Za-z0-9]{10,15}입니다 — 유효한 id 접미사가 없는 슬러그는 로컬에서 거부됩니다. API가 400 validation_error로 응답하기 때문입니다.

Requirements

• Node 18 이상 (내장 fetch 사용, 네이티브 의존성 없음).

• Outline 인스턴스 — 자체 호스팅 또는 Outline.com.

Getting started

git clone https://github.com/minhquan2904/outline-mcp.git
cd outline-mcp
npm ci

Get an API key

Outline에서: Settings → API & Apps → New API key. 값은 ol_api_로 시작하며 그 뒤에 38개의 영숫자 문자가 옵니다.

Set the two environment variables

export OUTLINE_API_URL=https://your-outline-instance
export OUTLINE_API_KEY=ol_api_…
node index.js

Configuration

서버는 정확히 두 개의 환경 변수를 읽습니다:

Claude Code — mcp.json (프로젝트) 또는 .mcp.json (사용자):

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

참고: Claude Desktop은 이 파일에서 ${VAR} 참조를 확장하지 않습니다 — 키를 그대로 붙여넣고 "${OUTLINE_API_KEY}"라고 쓰지 마세요.

다른 MCP 클라이언트 (Zed, Cline 또는 MCP stdio 프로토콜을 사용하는 모든 것) — 동일한 형태: 환경에 두 변수를 설정하고 node /path/to/outline-mcp/index.js를 실행하세요.

How it works

flowchart LR
    CC[Claude Code / any MCP client]
    OM[outline-mcp<br/>Node 18+, stdio server]
    O[Outline instance]
    F[format.js<br/>parse ref · truncate · render]
    C[client.js<br/>timeout · error map · 429 retry]

    CC -->|stdio| OM
    OM -->|"POST /api/{method} · Bearer ol_api_…"| O
    OM -.-> F
    OM -.-> C

서버는 시작 시 자격 증명을 검증하지 않습니다. 부팅 시 종료되는 서버는 클라이언트에 설명 없이 "연결 실패"로 표시됩니다. 대신 서버는 시작하고 도구를 나열하며 각 호출은 누락된 변수를 명명하는 메시지를 반환합니다.

Development

npm ci
npm test          # unit tests, fully offline (fetch is stubbed)
npm run smoke     # every tool against a real instance; no-ops without credentials

npm run smoke는 라이브 인스턴스를 가리키는 OUTLINE_API_URL + OUTLINE_API_KEY가 필요합니다. 없으면 "smoke skipped" 줄을 출력하고 0으로 종료합니다. 도구를 추가하는 방법은 CONTRIBUTING.md를 참조하세요.

Limitations

• 설계상 읽기 전용. 생성, 업데이트, 이동, 보관 또는 댓글 쓰기가 없습니다.

• 첨부 파일은 해석되지 않습니다. 포함된 이미지와 파일은 마크다운에서 /api/attachments.redirect?id=… 링크로 남아 있습니다. 텍스트를 읽는 에이전트에게는 로드되지 않습니다.

• 선제적 속도 제한 신호 없음. 인스턴스는 RateLimit-* 헤더를 반환하지 않습니다. 429 응답 시 클라이언트는 Retry-After(최대 10초)를 존중하고 정확히 한 번 재시도한 후 실패를 보고합니다.

• 긴 문서는 maxChars(기본 40,000)에서 잘리며 실제 총 길이를 명시하는 표시가 포함됩니다.

Security

API 키는 나가는 요청의 Authorization 헤더에만 포함됩니다. 클라이언트에서 나가는 모든 오류 메시지는 키를 ol_api_***로 대체하는 편집 단계를 거치며, 키의 경로(stdio 전송 또는 stderr 로그)에는 키 자체가 인쇄되지 않습니다. Outline 인스턴스가 범위 지정 키를 지원하는 경우 이 서버에는 읽기 전용 범위의 키를 사용하는 것이 좋습니다.

License

MIT — 전체 텍스트는 LICENSE를 참조하세요.