yandex-workspace-mcp

Purpose

yandex-workspace-mcp is a Model Context Protocol (MCP) server for integrating AI agents with Yandex Disk and Yandex Wiki. It provides AI assistants with a unified interface that enables them to search, read, and intelligently update data in Yandex Disk and Yandex Wiki without using web scraping or undocumented APIs.

Key Capabilities

Yandex Disk Integration

Provides 22 peer tools, plus disk_read and inline disk_upload, covering capacity, list/recent/search, metadata, signed links, upload, changes, public resources, trash, and bounded local tasks.

Yandex Wiki Integration

Provides 27 typed tools, plus a wiki_get_tree compatibility alias, covering search, page read/write, comments, resources, restore, attachments, and dynamic tables.

Unified Workspace Search

A single search tool allows agents to query Disk and Wiki simultaneously.

Security-First Architecture

• Read-only by default.
• Fine-grained permissions for read, write, and delete operations.
• Path allowlist (ALLOWED_ROOTS) strictly limits the scope of AI operations.
• Detailed, structured audit logging for all write/destructive operations.

Usage

Configuration

Copy .env.example to .env and fill in the corresponding values.

Authentication

HTTP deployment has three explicit modes: loopback development, static single-tenant bearer, and multi-user Yandex OAuth backed by encrypted in-memory/Redis state. CLI transport is verified before the server is built, authenticated HTTP requests fail closed when there is no SDK authentication context, and the MCP access token must be different from the Yandex credentials.

Steps to obtain an OAuth token:

1. Go to the Yandex OAuth portal.
2. Create a new client application.
3. Grant "Yandex.Disk REST API" (cloud_api:disk.read, cloud_api:disk.write, cloud_api:disk.info) and "Yandex Wiki" (wiki:read, wiki:write) permissions.
4. Generate an OAuth token and save it to the .env file.

For multi-user mode, register the exact HTTPS MCP_OAUTH_CALLBACK_URL instead of generating a global token, then set YANDEX_OAUTH_CLIENT_ID, YANDEX_OAUTH_CLIENT_SECRET, set both authentication modes to multi-user, configure Redis, and a separate cursor/encryption keyring.

Running

Run via the provided CLI. Run diagnostics and verify the configuration.

Client configuration

Add the corresponding configuration to the configuration file of the MCP client (such as Claude Desktop / Cursor).

Permission gating details

Wiki tools and permission gating

WIKI_READ exposes eight reference read tools plus wiki_get_tree. WIKI_WRITE adds page append/clone/comment operations plus grid create/update/copy/row/cell/column changes. WIKI_DELETE adds page/grid/row/column deletion and page restore. Local attachment upload additionally requires stdio and a non-empty WIKI_UPLOAD_ALLOWED_DIRS; it is never registered for remote transport.

Every locator and grid owner is resolved and checked against WIKI_ALLOWED_ROOTS before data is returned or changed. Grid changes require the caller to provide a revision, are serialized per grid within a single process, and conflicts are exposed rather than automatically replayed. Page cloning and grid copying only accept verified exact source operation URLs; these URLs are not returned to the MCP client.

Page deletion returns a random MCP restore handle instead of Yandex's token. The handle expires after 15 minutes, is bound to the principal, and is single-use, and the upstream token is encrypted at rest. Multi-user replicas store the handle in the same Redis backend as the OAuth state, so another replica can use them after a restart; local/static deployments use process-local handles. Remote deletion/restore requires MCP_TOKEN_ENCRYPTION_KEYS.

Disk tools and permission gating

DISK_READ exposes disk_info, list/recent/search/metadata/download,disk_list_trash and the bounded-text disk_read compatibility tool. disk_get_public_resource is additionally registered only when DISK_ALLOWED_PUBLIC_KEYS is non-empty. Every direct path is checked before the HTTP call; recent, search, embedded children, and trash results are post-filtered before output.

DISK_WRITE exposes inline upload, folder/copy/move/rename, publish/unpublish, and URL import when DISK_UPLOAD_URL_ALLOWED_HOSTS is non-empty. Local file upload and its four local task tools require stdio plus DISK_UPLOAD_ALLOWED_DIRS; they do not exist remotely. Tasks are bounded in memory, expire, never return source paths or credentials, and are cancelled on shutdown.

DISK_DELETE exposes resource deletion and trash restore. Permanent deletion of configured roots is rejected. disk_empty_trash does not exist unless the allowed roots include / and DISK_ALLOW_GLOBAL_DESTRUCTIVE=true; each call also requires the literal confirm=true.

Search contract and API drift

The canonical search tool concurrently queries Wiki and Disk, returns Wiki-first round-robin results, reports partial source failures, and uses a signed composite cursor. The standalone disk_search cursor and the canonical workspace cursor are different and are bound to the normalized query and the caller. Invalid or expired cursors fail closed.

Wiki full-text search uses POST /v1/search. This endpoint is tracked as YANDEX_API_DOCS_WIRE_DRIFT because the documented and observed Yandex fields may change independently. If the search endpoint is unavailable or its success response no longer matches the typed contract, the server uses a bounded descendants fallback. Fallback results are explicitly marked degraded=true and search_mode="descendants"; authentication, permission, rate limit, transport, validation, and normal empty-result cases never trigger the fallback.

Every Wiki/Disk result is post-filtered against the configured roots even if upstream filters were sent. An enabled service with no allowed roots causes startup failure. Signed download/upload uses a separate tokenless transport: it checks the HTTPS/Yandex suffix,all DNS answers, connected peers, redirects, and byte limits, without forwarding OAuth headers.

Applicable scenarios

Suitable for scenarios that require securely connecting AI agents to Yandex Disk and Yandex Wiki, for example letting an AI assistant search, read, and update enterprise or personal cloud drive and knowledge base content under controlled permissions while meeting audit and compliance requirements.

Limitations

• Read-only by default; writes and deletions require explicitly configured permissions.
• Local file upload and local task tools support only the stdio transport; remote transport is unavailable.
• Remote deletion/restore requires MCP_TOKEN_ENCRYPTION_KEYS.
• Enabled services must have allowed roots configured, otherwise startup fails.
• The search endpoint carries API drift risk and may trigger a degraded fallback.
• The offline example uses a mock upstream client and does not verify Yandex availability, live API consistency, load capacity, or a specific deployment.