Context7 — актуальная документация библиотек для Codex и Claude Code

Context7 — сервис Upstash, который добавляет актуальную документацию библиотек и примеры кода в контекст агента для разработки. Он помогает снизить риск устаревших API, выдуманных методов и кода для неподходящей версии пакета.

Содержание

1. Что это такое и как работает — принцип работы и выбор версии.
2. Режимы и инструменты — CLI, Skills и MCP.
3. Быстрая установка — автоматическая настройка через ctx7.
4. Подключение к Codex — плагин, локальный и удалённый MCP.
5. Подключение к Claude Code — setup, MCP и полный плагин.
6. Полезные сценарии — задачи с проверяемым результатом.
7. Проверка результата — как убедиться, что интеграция работает.
8. Лимиты и ограничения — версии Node.js, аутентификация и лимиты.

Что это такое и как работает

Обычный агент для разработки может опираться на данные, полученные во время обучения модели. Если библиотека с тех пор изменилась, ответ рискует содержать старый синтаксис.

Context7 выполняет два шага:

1. resolve-library-id находит библиотеку по названию и вопросу пользователя.
2. query-docs получает фрагменты документации по точному libraryId и конкретному запросу.

Если Context7 ID уже известен, первый шаг можно пропустить. Для GitHub-репозиториев ID обычно имеет вид /owner/repo, например /vercel/next.js. Версию можно закрепить двумя способами:

/vercel/next.js/v15.1.8
/vercel/next.js@v15.1.8

Режимы и инструменты

Поддерживаются два режима работы:

• CLI + Skills — установленный скилл вызывает команды ctx7 library и ctx7 docs; MCP-сервер не требуется.
• MCP — Codex или Claude Code вызывает инструменты Context7 через Model Context Protocol, стандарт подключения внешних инструментов к ИИ-клиентам.

Основные MCP-инструменты — resolve-library-id для поиска идентификатора библиотеки и query-docs для получения документации по этому идентификатору.

Один запрос лучше формулировать вокруг одного конкретного понятия. Для нескольких независимых тем делайте отдельные обращения: так результаты меньше размываются.

Быстрая установка

Универсальный установщик настраивает Context7 через CLI или MCP-режим, проводит вход через поток авторизации устройства (device flow) и создаёт конфигурацию:

npx ctx7 setup

# Сразу выбрать Claude Code
npx ctx7 setup --claude

Для Codex используйте общий мастер npx ctx7 setup; ручные варианты подключения приведены ниже.

Device flow показывает ссылку и короткий код. Ссылку можно открыть на другом устройстве, поэтому способ подходит для локальной машины, SSH-сервера и других окружений без браузера.

Удалить созданную настройку можно командой:

npx ctx7 remove

Подключение к Codex

Плагин Context7

Плагин подключает хостинговый MCP-сервер и добавляет скилл поиска документации:

codex plugin marketplace add upstash/context7
codex plugin add context7@context7-marketplace

После установки откроется вход через OAuth. Затем запустите новый тред Codex, чтобы загрузились инструменты и скилл.

Локальный MCP-сервер

Добавить сервер из терминала:

codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

Ручная конфигурация в ~/.codex/config.toml или проектном .codex/config.toml:

[mcp_servers.context7]
command = "npx"
# -y запускает пакет без отдельного подтверждения; API-ключ передаётся локальному серверу.
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
# Запас времени на первый запуск npx.
startup_timeout_ms = 20_000

Если первый запуск npx завершается по таймауту, увеличьте значение до 40_000.

На Windows официальный пример запускает npx через cmd:

[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
# Увеличенный запас времени на запуск через cmd и первый запуск npx.
startup_timeout_ms = 40_000

Удалённый MCP-сервер

Для удалённого MCP-сервера используйте стандартный заголовок Authorization:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
# Bearer-аутентификация с ключом Context7.
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

В changelog CLI 0.5.7 указано, что хостинговый сервер принимает и ранее использовавшийся заголовок CONTEXT7_API_KEY; для новой конфигурации используйте Authorization: Bearer.

Клиенты с поддержкой MCP OAuth могут подключаться к отдельному адресу:

https://mcp.context7.com/mcp/oauth

OAuth доступен только для удалённого HTTP-подключения. Локальный stdio-сервер использует API-ключ.

Подключение к Claude Code

Автоматическая настройка

npx ctx7 setup --claude

Установщик проводит вход через device flow, предлагает CLI- или MCP-режим и устанавливает скилл, который автоматически срабатывает на вопросах о библиотеках.

Только локальный MCP-сервер

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

--scope user включает сервер для всех проектов. Без этого флага настройка относится к текущему проекту.

Удалённое подключение:

claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp

Полный плагин

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

Плагин добавляет:

Актуальный changelog пакета @upstash/context7-mcp 4.0.5 указывает, что плагин Claude Code требует аутентификацию. Перед запуском Claude Code задайте ключ:

export CONTEXT7_API_KEY="YOUR_API_KEY"

После изменения окружения перезапустите Claude Code.

Когда основной диалог уже длинный, документацию можно вынести в отдельного агента:

Промпт:

spawn docs-researcher: как настроить Prisma с PostgreSQL?

Для короткого запроса используйте команду плагина:

Промпт:

/context7:docs /supabase/supabase row level security

Полезные сценарии

Получить код для конкретной версии

Задача: настроить middleware для Next.js 15 без смешения синтаксиса разных версий.

Промпт:

Как настроить middleware в Next.js 15 для проверки JWT в cookie? use context7

Если известен точный ID, укажите его сразу:

Промпт:

use context7 with /vercel/next.js for Next.js 15 middleware authentication

Наблюдаемый результат: агент вызывает Context7 и строит ответ по выбранной библиотеке или версии. Если нужной версии нет в индексе, ответ требует сверки с официальной документацией проекта.

Уточнить текущий API библиотеки

Задача: получить актуальный синтаксис row-level security в Supabase.

Промпт:

Покажи актуальный синтаксис Supabase для row-level security. use context7

Наблюдаемый результат: сначала определяется библиотека, затем возвращаются релевантные фрагменты документации. Для нишевого или неоднозначного пакета лучше передать точный ID.

Работать через CLI без MCP

# Найти библиотеку
ctx7 library next.js "app router middleware"

# Получить документацию по известному ID
ctx7 docs /vercel/next.js "app router middleware"

Наблюдаемый результат первой команды — найденный Context7 ID и сведения о совпадении. Вторая команда возвращает документацию по указанной теме. Если результат поиска неоднозначен, уточните ID перед второй командой.

Проверка результата

После установки перезапустите клиент или откройте новый тред, затем выполните минимальную проверку:

1. Попросите документацию для известной библиотеки и одной конкретной темы.
2. Убедитесь, что клиент видит инструменты resolve-library-id и query-docs либо использует команды ctx7 в CLI-режиме.
3. Передайте точный ID, например /vercel/next.js, и проверьте, что поиск библиотеки пропущен.
4. Укажите версию и убедитесь, что ответ не смешивает её с другой веткой документации.

Если сервер не запускается:

• проверьте, что для локального MCP установлен Node.js 20.18.1+;
• увеличьте startup_timeout_ms до 40_000;
• на Windows запускайте npx через cmd /c;
• для удалённого подключения проверьте адрес и заголовок Authorization: Bearer YOUR_API_KEY;
• для Claude Code plugin проверьте CONTEXT7_API_KEY и перезапустите клиент.

Материал основан на официальной документации и changelog; команды не проверялись реальным запуском в пользовательском окружении.

Лимиты и ограничения

• Без API-ключа некоторые MCP-подключения работают с низкими анонимными лимитами. Аутентифицированные запросы получают лимиты своего тарифа.
• Прямые запросы к Context7 API требуют заголовок Authorization: Bearer CONTEXT7_API_KEY.
• При превышении API-лимита возвращается HTTP 429. Ориентируйтесь на Retry-After, RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset.
• Качество результата зависит от доступной документации конкретной библиотеки и правильности выбранного ID.
• Один запрос к query-docs лучше посвящать одному понятию. Для независимых тем используйте отдельные запросы.
• MCP-сервер ограничивает один вопрос максимум тремя вызовами инструментов, чтобы не раздувать контекст.

Официальные ссылки

• Репозиторий Context7
• Настройка MCP-клиентов
• Руководство для Claude Code
• Context7 API Guide
• Changelog MCP-сервера
• Changelog CLI

Следующий шаг

Skills: Codex vs Claude Code — сравнение и совместимость

Если вы настраиваете работу с документацией для Codex или Claude Code, можно отдельно разобрать выбор между локальным MCP, удалённым сервером и CLI-режимом.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov