English | Русский

Yandex Wiki Search MCP

Claude, Cursor, Windsurf 또는 모든 MCP 클라이언트를 Yandex Wiki에 연결할 수 있습니다: 전문 검색, 페이지, 댓글, 첨부 파일, 그리고 동적 테이블("grids") — 33개의 도구가 타입 스키마와 함께 제공됩니다.

비공식 프로젝트입니다 — Yandex와 관련이 없거나 보증을 받지 않습니다.

• 🔍 전문 검색 — 위키 전체를 대상으로 하며, Wiki 웹 검색창과 동일한 백엔드를 사용합니다. 쿼리당 최대 50개의 결과.

• 📄 전체 페이지 수명주기 — 생성, 수정, 추가(상단 / 하단 / 앵커), 복제, 복구 토큰을 통한 삭제, 댓글, 파일 업로드.

• 📊 동적 테이블 (grid) — 11개의 쓰기 도구: 행, 열, 셀, 복사, 정렬.

• 🔒 서버 측 읽기 전용 모드 — WIKI_READ_ONLY=true로 설정하면 쓰기 도구가 아예 등록되지 않으므로 에이전트가 우회할 수 없습니다.

• 🧩 타입이 지정된 도구 표면 — 모든 도구에 입력 및 출력 JSON 스키마와 안전 주석(읽기 전용 / 파괴적 작업 / 멱등성 힌트)을 포함합니다.

• 🐳 어디서나 실행 — 데스크톱 클라이언트용 stdio, 팀용 streamable-http든 Docker(선택적 다중 사용자 OAuth)를 지원합니다.

Quick start

1. Wiki 접근이 있는 Yandex OAuth 토큰(공식 가이드)과 조직 ID를 받습니다.

2. 클라이언트에 설치합니다:

    ! 

웹 배지가 오래되어 최신 양을 대신: 아래 참고.

Claude Desktop 배지로 받기 : .mcpb 번들을 더블 클릭하면 Claude Desktop이 서버를 설치하고 토큰과 조직 ID를 요청합니다. uv가 필요합니다.

{
  "mcpServers": {
    "yandex-wiki-search": {
      "command": "uvx",
      "args": ["yandex-wiki-search-mcp"],
      "env": {
        "WIKI_TOKEN": "YOUR_TOKEN",
        "WIKI_ORG_ID": "YOUR_ORG_ID",
        "WIKI_READ_ONLY": "true"
      }
    }
  }
}

claude mcp add yandex-wiki-search \
  -e WIKI_TOKEN=YOUR_TOKEN -e WIKI_ORG_ID=YOUR_ORG_ID -e WIKI_READ_ONLY=true \
  -- uvx yandex-wiki-search-mcp

{
  "mcpServers": {
    "yandex-wiki-search": {
      "command": "docker",
      "args": ["run","--rm","-i",
        "-e","WIKI_TOKEN","-e","WIKI_ORG_ID","-e","WIKI_READ_ONLY=true",
        "ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest"],
      "env": {"WIKI_TOKEN":"YOUR_TOKEN","WIKI_ORG_ID":"YOUR_ORG_ID"}
    }
  }
}

[!TIP] WIKI_READ_ONLY=true로 시작하세요. 그럼 서버가 쓰기 도구를 등록하지 않습니다. 에이전트가 편집을 해도 될 만큼 신뢰하게 되면 false로 바꾸세요.

3. AI 에이전트에게 예시처럼 요청해 보세요 — 아래 참고.

서버는 MCP Python SDK v2로 실행됩니다. 클라이언트에서는 볼 수 없습니다 — v2 서버 하나가 2024-11-05까지의 모든 프로토콜 리비전과 현재 버전을 모두 대응하므로, 사용자 측에서 바꿀 일도 재설치할 일도 전혀 없습니다.

과거 버전을 써야 하는 유일한 이유는 다른 작업 때문에 mcp<2를 고정한 공용 환경을 사용할 때뿐입니다. 1.0.1은 1.x SDK로 빌드된 마지막 릴리스이며, PyPI에 남아 있습니다:

pip install "yandex-wiki-search-mcp<1.1"

Related MCP server: mediawiki-mcp-server

할 수 있는 작업

"온보딩 문서를 찾아 핵심 단계를 요약해 주세요."

"인시던트 대응에 대해 어떤 문서가 있나요? 가장 관련 깊은 페이지를 열어 주세요."

"team/weekly-notes 페이지를 만들고 오늘의 스탠드업 요약을 뒤에 추가해 주세요."

"당직 로테이션 그리드에 행을 추가하세요: alice, 다음 주."

"이 PDF를 프로젝트 페이지에 업로드하고 하단에 링크를 걸어 주세요."

"초안 페이지를 삭제하되, 마음이 바뀔 경우에 대비해 복구 토큰은 보관해 주세요."

도구

33개의 도구입니다. WIKI_READ_ONLY=true로 설정하면 모든 쓰기 도구가 사라집니다.

검색 및 읽기 (10)

페이지: 쓰기 (12)

กริด: write (11)

ข้อมูลเฉพาะของกริด:

• การแก้ไขข้อมูล (mutations) ใช้ optimistic locking — ให้ fetchกริดก่อนแล้วส่ง revision ล่าสุดไป

• grid_update.default_sort มีรูปแบบ entry เป็น [{"column": "status", "direction": "asc"}]; server จะแปลงให้เป็น wire format ที่ API ต้องการ

• grid_add_columns จำเป็นต้องระบุ required ทุุกคอลัมน์เพราะ API จริงทำการตรวจสอบค่าตรงนี้

• grid_copy return ค่า operation metadata ไม่ใช่ object กริดที่ทำการคัดลอกไว้.

##การเปรียบเทียบ

ข้อเท็จจริงได้ถูกตรวจสอบจากเอกสารและซอร์สโค้ดของทางเลือกอื่นๆ ในช่วงกรกฎาคม–สิงหาคม 2026; รายการของ tool ของ hosted server อย่างเป็นทางการนั้นดึงข้อมูลมาจาก mcp.wiki.yandex.net (wiki-mcp-server 1.28.1, 2026-08-1)

또한 알아두면 좋은 사항:

• best-doctor/mcp-yandex-wiki (Python) — 페이지 생성 / 업데이트 및 읽기, 별도 -ro 읽기 전용 엔트리 포인트 포함; 삭제 / 복구, 그리드, 검색 없음; PyPI만 배포

• brekhov-ilya/yandex-wiki-mcp (npm) — 페이지 읽기 / 쓰기 / 이동, 그리드 읽기 전용; 자동 갱신을 지원하는 대화형 PKCE 토큰 흐름, 전체 텍스트 검색 없음

• n-r-w/yandex-mcp (Go) — Yandex Tracker + Wiki를 하나의 서버에 통합, 원래 설계상 읽기 전용(위키 읽기 도구 5개), 검색 없음; yc CLI의 IAM 토큰으로만 인증 — Yandex OAuth 토큰은 지원되지 않음

• bim-ba/ycli (Python) — Tracker + Wiki + Forms 전용 툴킷: CLI, Python SDK, Claude Code 플러그인, 위키 표면을 42개의 wiki_* 도구(15 읽기 / 27 쓰기, 주석, --read-only 플래그 포함)로 갖춘 MCP 서버; 전체 텍스트 검색 도구 없음, 첨부 파일 다운로드는 CLI/SDK 전용

2026년 8월 기준으로 전체 텍스트 검색은 여기(최대 50개 결과)와 slartus(최대 10개)에만 구현되어 있습니다 — Yandex 자체 호스팅 서버에는 검색 도구가 없습니다 — 그리고 검색, 그리드 쓰기, 서버 측 읽기 전용 모드, 타입화된 스키마의 조합은 이 프로젝트에만 있습니다.

이 프로젝트는 ya-yandex-wiki-mcp의 포크이며 slartus/mcp-yandex-wiki의 성과를 기반으로 합니다 — 크레딧을 참조하세요.

전체 텍스트 검색

page_search는 POST /v1/search 엔드포인트를 래핑합니다 — 위키 웹 검색창을 구동하는 것과 동일한 백엔드이며, 2026년 8월 Yandex가 API 참조 문서를 공개할 때까지 문서화되지 않았습니다. 검색을 먼저 수행한 다음, 결과를 slug로 page_get을 호출하여 여십시오.

• 두 가지 동작 모드. 기본값: 한 번의 호출에서 최대 50개 결과(limit는 1–50으로 제한됨; API는 그 외 값을 거부) 및 페이지네이션 없음 — 응답 커서는 항상 null입니다. highlight=true를 사용할 때: limit와 무관하게 페이지가 10개 결과로 하드 상한되고, 일치 항목은 <em>으로 감싸지며, cursor(next_cursor에 반영되는 페이지 번호)는 최대 ~100개 결과를 탐색합니다. results가 비어 오거나 next_cursor가 null인(비어 있지 않은 페이지에서) 상태에서 종료됩니다. 끝을 지니고 next_cursor는 빈 페이지들 위에서 계속 증가하므로, null이라는 것만으로 “더 존재한다”는 의미는 아닙니다.

• 필터는 limit 적용 전에 서버 측에서 실행됩니다 — 필터링된 검색에서도 일치 항목을 잃지 않습니다: slug_prefix(섹션 필터, tech-doc/ml 같은 깊은 접두사 허용), result_type(page/file), authors(uid/cloud_uid로 페이지 소유자 — user_get_current가 자신의 소유자 ID로 제공하여 “X에 대한 페이지 찾기”를 두 번의 호출로 해결), 그리고 created_between/modified_between 날짜 구간(양쪽 경계값 모두 필요 — 열린 구간은 API가 거부).

• 따옴표 ””로 감싼 “exact phrase” 쿼리가 작동합니다. page 결과에는 절대 https://wiki.yandex.ru/... 링크, file 결과는 직접 다운로드 링크가 반환됩니다.

• content는 ~510자 분량의 발췌로서, 페이지가 아니라 요약도 아닙니다. 일치하는 위치에서 잘려 나오며, 검색어는 그 안에 반드시 포함되지 않을 수 있고, 줄바꿈과 탭은 조각 사이의 구분자가 아닌 페이지 자체의 레이아웃입니다(테이블 셀은 탭으로 구분되어 있RISE). highlight=true로 전달하면 <em> 태그로 감싼 일치 항목을 얻을 수 있습니다. 응답하기 전에 page_get으로 페이지 전체를 읽으세요. file 결과에서는 비어합니다.

트리 탐색

page_get_descendants는 하위 트리를 모든 중첩 수준에서 하나의 평면 목록으로 {id, slug} 형태로 반환합니다. page_id/slug 대신 from_root=true를 전달하면 전체 Wiki를 탐색합니다. 시작 slug를 모를 때 들어가는 경로이므로 검색이 유일한 입구는 아닙니다. 알고 있는 섹션 slug가 있으면 그 슬러그를 우선 사용하세요. 위키는 수천 페이지에 달할 수 있으며, fetch_all은 ~500개 항목 한도에 도달하면 truncated: true로 중지합니다.

검증된 추가 API 동작(스코프, 403 시맨틱, 오류 봉투, 제한): docs/api-notes.md.

설정

OAUTH_ENABLED=true이면 서버가 OAuth 제공자가 됩니다. 각 MCP 사용자는 자신의 Yandex 계정으로 인증하며, Wiki API 요청은 해당 사용자의 개인 토큰으로 이루어집니다. page_upload_attachment 도구와 page_download_attachment 도구는 이 모드에서 등록되지 않습니다. 이 도구들은 서버가 실행되는 머신에서 파일을 읽고 쓰는데, 공유 배포 환경에서는 그 머신이 호출자의 머신이 아니기 때문입니다.

사용자별 조직 선택. WIKI_ORG_ID / WIKI_CLOUD_ORG_ID는 OAuth에서 선택 사항입니다. 각 요청이 자신의 조직을 지정할 수 있기 때문입니다. 클라이언트가 연결하는 MCP 서버 URL에 ?orgId=... (또는 ?cloudOrgId=...)를 추가하면 됩니다. 쿼리 매개변수는 서버 전체 설정보다 우선하므로, 하나의 배포로 여러 조직을 서비스할 수 있습니다. 요청에 둘 다 없으면 도구 호출은 두 옵션을 모두 안내하는 메시지와 함께 실패합니다. 모든 사용자가 하나의 조직을 공유한다면 환경 변수를 기본값으로 설정하세요.

전체 주석 목록은 .env.example을, Redis 기본 구성은 compose.yaml을 참조하세요.

배포

flowchart LR
    C["MCP client<br/>Claude / Cursor / Windsurf / VS Code"]
    S["yandex-wiki-search-mcp"]
    W["Yandex Wiki API"]
    R[("Redis<br/>optional OAuth token store")]
    C -- "stdio (local, single user)" --> S
    C -- "streamable-http (+ OAuth, multi-user)" --> S
    S --> W
    S -.-> R

Docker 기반 HTTP 서버 (MCP 엔드포인트: http://localhost:8000/mcp):

docker run --env-file .env -e TRANSPORT=streamable-http -p 8000:8000 \
  --log-opt max-size=10m --log-opt max-file=3 \
  ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest

[!NOTE] 서버는 자체 로그 파일을 만들지 않습니다. 모든 로그는 stderr로 전달되며, Docker의 기본 json-file 드라이버는 크기 제한 없이 저장합니다. 위의 --log-opt 플래그가 이를 제한합니다. 데몬에서 이미 기본값을 설정한다면 그 플래그만 제거하세요.

services:
  mcp-wiki:
    image: ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest  # or: build: .
    ports:
      - "8000:8000"
    environment:
      - WIKI_TOKEN=${WIKI_TOKEN}
      - WIKI_ORG_ID=${WIKI_ORG_ID}
      - TRANSPORT=streamable-http
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Redis 기반 OAuth 저장소에는 기존 compose.yaml을 기준으로 사용하세요.

보안

• 읽기 전용은 서버 측에서 적용: WIKI_READ_ONLY=true이면 쓰기 도구가 전혀 등록되지 않습니다. 혼란스러운 에이전트가 호출할 대상이 없습니다.

• Wiki API는 OAuth 스코프를 강제하지 않습니다 (Yandex가 스코프를 문서화한 이후 2026-08-11에 재확인 — docs/api-notes.md 참조): wiki:read 토큰으로도 쓰기가 가능하므로, 토큰 스코프에 의존하지 말고 읽기 전용 모드를 사용하세요.

• 비밀 값은 전체에서 SecretStr로 처리됩니다. 로그와 repr에서 마스킹되며, DEBUG HTTP 로깅에는 헤더나 본문이 절대 포함되지 않습니다.

• 삭제는 복구 가능합니다. page_delete는 page_recover에 사용할 복구 토큰을 반환합니다.

• 공유 .env에 있는 관련 없는 키는 무시되지만, 철자가 틀린 설정(WIKI_READ_ONL)은 선택하지 않은 기본값으로 조용히 대체하는 대신 서버를 중단시킵니다.

개발

uv sync --dev
uv run yandex-wiki-search-mcp   # run locally
uv run pytest                   # tests

커밋하기 전에 CONTRIBUTING.md의 전체 검증 세트를 실행하세요. 서버가 어떻게 구성되는지(계층, 코드 지도, 테스트 연결 지점, CI 및 릴리스 프로세스)는 docs/architecture.md에 설명되어 있습니다. 검증된 API 동작과 프로브 스크립트는 docs/api-notes.md에 문서화되어 있습니다.

Wiki API는 드리프트(drift)가 있습니다(검색 엔드포인트는 문서화되기 전에 이미 한 번 조용히 계약을 변경한 적 있습니다) — scripts/contract_sweep.py는 모든 클라이언트 메서드를 라이브 조직을 대상으로 다시 검증하고, 검증 불일치와 선언되지 않은 키를 보고합니다:

uv run python scripts/contract_sweep.py users/YOU/contract-sweep            # ~30 live checks
uv run python scripts/contract_sweep.py users/YOU/contract-sweep --cleanup  # remove fixtures

API 드리프트 검사 워크플로는 DRIFT_* 저장소 시크릿이 구성되어 있을 때 동일한 검사를 매주 실행합니다(지침은 워크플로 헤더에 있습니다). 구성되어 있지 않으면 조용히 건너뜁니다.

크레딧

이 프로젝트는 Aleksandr Ponkratov가 만든, Yandex Wiki API용으로 잘 테스트된 훌륭한 Python MCP 서버인 APonkratov/yandex-wiki-mcp(ya-yandex-wiki-mcp)의 포크로 시작했습니다. 그 이후로 이 프로젝트는 나름의 표면을 갖추게 되었습니다 — 전체 텍스트 검색, 33개 도구 전체에 걸친 타입 지정 입력 및 출력 스키마, YFM 헬퍼, 커서 드레이닝, 다중 사용자 OAuth, 그리고 API에 대한 라이브 계약 검사 — 원래 저작권과 라이선스는 그대로 보존됩니다(LICENSE 및 NOTICE 참조).

전체 텍스트 검색의 아이디어와 핵심 API 발견은 slartus/mcp-yandex-wiki(JavaScript, MIT)에서 나왔습니다. 이 프로젝트는 당시 문서화되지 않았던 POST /v1/search 엔드포인트를 처음으로 발견했고(Yandex는 이에 대한 참조 문서를 2026년 8월에야 게시했습니다), OAuth 스코프가 강제되지 않는다는 사실을 처음으로 보고했습니다. 이 프로젝트의 어떤 코드도 가져오지 않았습니다 — 오직 발견 사항과 아이디어만을 라이브 조직에 대해 독립적으로 다시 검증하고 여기에서 확장한 것입니다.

상표

"Yandex" 및 "Yandex Wiki"는 YANDEX LLC의 상표입니다. 이 프로젝트는 비공식적이고 커뮤니티 기반 프로젝트로서, Yandex와 제휴, 후원, 보증 관계가 없습니다 — 이름은 단지 이 서버가 어떤 서비스에 연결하는지 밝히기 위해 명목적으로 사용됩니다. 로고는 Yandex Wiki나 MCP 브랜딩을 재현하지 않는 독창적인 마크입니다(디자인 노트).

mcp-name: io.github.dlbolshov/yandex-wiki-search-mcp