Yandex Cloud Docs MCP

Offline, read-only full-text search for a local checkout of the Yandex Cloud documentation, exposed as a Model Context Protocol (MCP) server.

The server is designed for local use with Claude Code, Claude Desktop, Codex, and other MCP clients that support the stdio transport. It does not call a remote documentation service, require authentication, or send documentation content over the network.

[!NOTE] The prebuilt Yandex Cloud Markdown corpus is primarily in Russian. The server instructs MCP clients to translate core technical search terms to Russian when the user's question is in another language.

Features

• Local SQLite FTS5 index with ranked full-text search.
• Line-numbered excerpts and document reads for precise citations.
• Incremental refresh after upstream Git updates.
• Explicit status reporting for the docs revision, index revision, file count, dirty working tree, and stale index state.
• Read-only MCP tool annotations.
• Path traversal and symlink-escape protection.
• Atomic full-index rebuilds.
• No remote fallback and no runtime network access.

MCP tools

Tool	Purpose
search_yandex_cloud_docs	Search the local index and return ranked paths, excerpts, and line ranges.
read_yandex_cloud_doc	Read up to 400 numbered lines from a document returned by search.
yandex_cloud_docs_status	Compare the indexed revision with the current documentation checkout.

Requirements

• Git.
• Node.js 25.7 or newer.
• An MCP client with local stdio support.
• A local checkout of yandex-cloud/docs containing md-docs/.

The commands below use a POSIX shell on macOS or Linux. Windows users can use the same directory layout with absolute Windows paths in the client configuration.

Quick start

The recommended layout keeps the upstream documentation and this MCP server in one parent directory:

yc-docs/
├── docs/    # yandex-cloud/docs
└── mcp/     # this repository

Choose an absolute installation directory and clone both repositories:

export YC_DOCS_HOME="${YC_DOCS_HOME:-$HOME/src/yc-docs}"

mkdir -p "$YC_DOCS_HOME"
git clone https://github.com/yandex-cloud/docs.git "$YC_DOCS_HOME/docs"
git clone https://github.com/selivanov-tech/yandex-cloud-docs-mcp.git \
  "$YC_DOCS_HOME/mcp"

Install dependencies and compile the server:

cd "$YC_DOCS_HOME/mcp"
npm ci
npm run build

Build the local index:

npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"

The first build is a full scan. Later builds use the Git history to update changed Markdown files incrementally. The generated dist/, node_modules/, and var/ directories are intentionally excluded from Git.

Prepare absolute client paths

All runtime paths must be absolute. These shell variables make the rollout commands easier to copy:

export NODE_BIN="$(command -v node)"
export MCP_SERVER="$YC_DOCS_HOME/mcp/dist/src/server.js"
export DOCS_ROOT="$YC_DOCS_HOME/docs/md-docs"
export DOCS_INDEX="$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"

Confirm that every path exists before configuring a client:

test -x "$NODE_BIN"
test -f "$MCP_SERVER"
test -d "$DOCS_ROOT"
test -f "$DOCS_INDEX"

Roll out to Claude Code

User scope

User scope makes the server available in every Claude Code project on the machine:

claude mcp add \
  --transport stdio \
  --scope user \
  yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"

Verify the connection:

claude mcp get yandex-cloud-documentation

Project scope

To share the server definition through a project's .mcp.json, run the same command from that project with --scope project:

claude mcp add \
  --transport stdio \
  --scope project \
  yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"

Claude Code asks each user to approve project-scoped MCP servers. Start an interactive claude session in the project to review the prompt. Because the generated paths are machine-specific, do not commit that .mcp.json for a team unless you replace them with shared environment-variable conventions.

Roll out to Claude Desktop

This repository currently ships as a developer-installed stdio server rather than a packaged .mcpb desktop extension.

Open the Claude Desktop configuration file:

Platform	Configuration path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Merge the following entry into the existing mcpServers object. Replace every placeholder with an absolute path; JSON configuration does not run the shell variables from the previous section.

{
  "mcpServers": {
    "yandex-cloud-documentation": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/yc-docs/mcp/dist/src/server.js",
        "--docs-root",
        "/absolute/path/to/yc-docs/docs/md-docs",
        "--index",
        "/absolute/path/to/yc-docs/mcp/var/yandex-cloud-docs.sqlite"
      ]
    }
  }
}

Fully quit and reopen Claude Desktop. Use + → Connectors in the composer, or open the desktop developer settings, to confirm that yandex-cloud-documentation is connected and exposes three tools.

Roll out to Codex

The Codex CLI command installs the server in the user's Codex configuration:

codex mcp add yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"

Verify the stored configuration:

codex mcp get yandex-cloud-documentation --json

Alternatively, add the server directly to ~/.codex/config.toml:

[mcp_servers.yandex-cloud-documentation]
command = "/absolute/path/to/node"
args = [
  "/absolute/path/to/yc-docs/mcp/dist/src/server.js",
  "--docs-root",
  "/absolute/path/to/yc-docs/docs/md-docs",
  "--index",
  "/absolute/path/to/yc-docs/mcp/var/yandex-cloud-docs.sqlite",
]

For project-only access, put the same table in .codex/config.toml inside a trusted project. Start a new Codex session after changing MCP configuration.

Smoke test

Ask the client:

Use yandex-cloud-documentation to find the documentation for creating a
service account. Cite the local document path and line numbers, then report
whether the local index is stale.

A successful response should use the search, read, and status tools; cite a path such as iam/operations/sa/create.md; and report stale: false.

Update the documentation and index

Pull upstream documentation changes:

git -C "$YC_DOCS_HOME/docs" pull --ff-only

Refresh the index:

cd "$YC_DOCS_HOME/mcp"
npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"

Use --rebuild to force an atomic full rebuild:

npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite" \
  --rebuild

The MCP runtime never updates the checkout or index automatically. This keeps runtime tool calls read-only and makes documentation updates explicit.

Update the MCP server

cd "$YC_DOCS_HOME/mcp"
git pull --ff-only
npm ci
npm run build

Restart Claude Desktop and begin new Claude Code or Codex sessions if the server process was already running.

Run directly

The server communicates over stdio:

"$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"

Protocol messages are written to stdout. Startup and fatal errors are written to stderr.

Development

Install and test:

npm ci
npm test

The test suite covers:

• Full and incremental indexing.
• Search, numbered reads, and index status.
• Additions, modifications, and deletions.
• Path traversal and symlink escapes.
• MCP tool discovery and calls over an in-memory transport.

Troubleshooting

Both --docs-root <path> and --index <path> are required

Both arguments must be present in the client configuration.

--docs-root and --index must be absolute paths

Resolve shell variables before saving client configuration. Claude Desktop JSON and Codex TOML examples must contain literal absolute paths.

spawn node ENOENT or Server disconnected

GUI applications often have a smaller PATH than an interactive shell. Use the absolute path returned by command -v node as the MCP command.

The index is missing or stale

Run the index refresh command, then call yandex_cloud_docs_status again. A dirty documentation checkout triggers a safe full rebuild.

Claude Code shows Pending approval

Open an interactive Claude Code session in the project and approve the project-scoped .mcp.json entry.

Claude Desktop does not show the tools

Validate the JSON, confirm all paths exist, fully restart Claude Desktop, and check the MCP server logs from the desktop developer settings.

Security model

• MCP runtime tools are local and read-only.
• The runtime makes no network requests.
• The index command writes only to the configured SQLite path.
• Document reads are confined to the configured docs root.
• Generated data and the upstream documentation checkout are not bundled in this repository.

Review any local MCP server before enabling it, especially when using a project-scoped configuration from a repository you do not control.

Upstream documentation

• Yandex Cloud documentation repository
• Model Context Protocol
• Claude Code MCP documentation
• Claude Desktop local MCP servers
• Codex MCP documentation

License

Copyright 2026 Sergey Selivanov.

The MCP server and its documentation are licensed under the Apache License 2.0. The separately cloned Yandex Cloud documentation remains subject to its upstream license.

Disclaimer

This is an unofficial community project. It is not affiliated with or endorsed by Yandex, Anthropic, or OpenAI. Yandex Cloud documentation and trademarks remain the property of their respective owners and are subject to the upstream repository's terms.