denis-samatov/yandex-workspace-mcp

A Model Context Protocol (MCP) server with explicit permission controls for integrating AI agents with **Yandex Disk** and **Yandex Wiki**.
This server provides a unified interface for AI assistants to search, read, and intelligently update data in Yandex Disk and Yandex Wiki, without resorting to scraping or undocumented APIs.
At a glance
| | |
|---|---|
| **What** | MCP server that gives AI agents governed access to Yandex Disk and Yandex Wiki. |
| **Scope** | 50+ typed tools; unified Disk + Wiki search. |
| **Safety** | Read-only by default, separate read/write/delete permissions, path allowlisting, structured audit log of write and destructive operations. |
| **Quality** | Security and permission regression tests, opt-in live contract sweep, CI, Docker. |
| **Limits** | The offline demo uses a mocked upstream; it does not validate live API parity or load capacity. |
Start here
- **Review the engineering:** run the credential-free permission demo and inspect permission regression tests.
- **Connect a client:** follow the minimal read-only quick start, then the client configuration below.
- **Deploy:** read authentication, deployment, and security.
The offline example uses a mocked upstream client. It demonstrates local authorization behavior; it does not validate Yandex availability, live API parity, load capacity, or a particular deployment. The opt-in contract sweep below checks a different, live integration boundary.
Test the tool exposure policy
The development test suite uses mcp-capguard
to check readonly, editor without deletion, and disabled-service profiles against
the real application factory. No API keys are needed and no tools are invoked:
The four tests include a negative control that enables actual Wiki write settings
while keeping the readonly policy and confirms that capguard rejects the write
tools. The standard CI pytest step runs these tests on every supported platform.
Only explicitly required and forbidden tool names are checked; maintain the
policy in tests/capguard_profiles.py when adding tools.
These checks complement the existing exact registration, service authorization,
and API contract tests.
Features
- **Yandex Disk Integration**: 22 parity tools plus disk_read and inline disk_upload cover capacity, list/recent/search, metadata, signed links, uploads, mutations, public resources, Trash, and bounded local jobs.
- **Yandex Wiki Integration**: 27 typed tools plus the wiki_get_tree compatibility alias cover search, page reads/writes, comments, resources, recovery, attachments, and dynamic tables.
- **Unified Workspace Search**: A single search tool allows agents to query both Disk and Wiki simultaneously.
- **Security-First Architecture**:
- Read-only by default.
- Granular permissions for read, write, and delete operations.
- Path allowlisting (ALLOWED_ROOTS) to strictly confine AI operations.
- Detailed, structured audit logging of all write/destructive operations.
Installation
Configuration
Copy .env.example to .env and fill in the values:
HTTP deployments have three explicit modes: loopback development, static single-tenant bearer, and multi-user Yandex OAuth backed by encrypted memory/Redis state. CLI transport overrides are validated before server construction, authenticated HTTP requests fail closed without an SDK auth context, and MCP access tokens must be distinct from Yandex credentials. See authentication and deployment for IAM headers, scopes, PKCE, callback registration, key rotation, TLS/proxy rules, and Compose profiles.