Запустите сервер MCP Neo4j на собственном компьютере с помощью Docker и VS Code
Установите Neo4j и его официальный сервер MCP самостоятельно с помощью Docker Compose, защитите их с помощью базовой аутентификации через HTTP, подключите VS Code в режиме Agent и выполните запрос к демонстрационной графе.
Источники: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)
Официальный сервер MCP от Neo4j — это небольшая программа, и вся инфраструктура может быть запущена на ноутбуке с Docker примерно за полчаса. Это важно для всех, кто проходит курс GraphAcademy по разработке с инструментами MCP от Neo4j, поскольку курс предполагает использование GitHub Codespaces, у которого есть ежемесячный бесплатный лимит, который со временем исчерпывается. Самостоятельное хостингование устраняет это ограничение и не требует никаких затрат. Приведённые ниже шаги были выполнены полностью, и они также показывают, как компоненты MCP взаимодействуют между собой.
Что будет создано
VS Code (host) ──HTTP /mcp + auth──► neo4j-mcp (server) ──Bolt──► Neo4j (database)
Структура состоит из трех отдельных компонентов, и четкое понимание их разделения помогает в работе.
- Хост: клиент MCP, например VS Code, Claude Desktop или Cursor. Он обрабатывает протокол MCP и не имеет ни малейшего представления о существовании Neo4j.
- Сервер MCP: мост
neo4j-mcp, который преобразует запросы инструментов MCP, такие какread-cypher, в реальные запросы Bolt. - База данных: сам Neo4j.
Частым заблуждением является представление о том, что какая-то удаленная «база данных MCP» находится в облаке. Это не так. Сервер MCP — это программа, которая запускается локально, и она подключается к той базе данных, к которой направлена.
Предварительные требования
Необходимо установить и запустить Docker Desktop, что можно подтвердить командой docker --version. Также требуется VS Code с поддержкой MCP и терминал. Установка Python и Neo4j не обязательна, поскольку Docker уже покрывает их функции.
Шаг 1: Создание стека Docker
Создайте папку проекта и поместите в неё файл docker-compose.yml. В этом файле определяются два сервиса. Сначала идет база данных:
services:
neo4j:
image: neo4j:5.26
container_name: neo4j
ports:
- "7474:7474" # Neo4j Browser -> http://localhost:7474
- "7687:7687" # Bolt
environment:
NEO4J_AUTH: "neo4j/password123"
NEO4J_PLUGINS: '["apoc","graph-data-science"]' # needed for get-schema + GDS tool
volumes:
- neo4j_data:/data
healthcheck:
test: ["CMD-SHELL", "cypher-shell -u neo4j -p password123 'RETURN 1' || exit 1"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
Во-вторых идет сервер MCP, собранный непосредственно из официального репозитория по фиксированному тегу:
neo4j-mcp:
build:
context: "https://github.com/neo4j/mcp.git#v1.5.2" # builds the official server from source
container_name: neo4j-mcp
depends_on:
neo4j:
condition: service_healthy
ports:
- "8000:8000" # MCP endpoint -> http://localhost:8000/mcp
environment:
NEO4J_URI: "bolt://neo4j:7687"
NEO4J_DATABASE: "neo4j"
NEO4J_TRANSPORT_MODE: "http" # networked service, not a stdio subprocess
NEO4J_MCP_HTTP_HOST: "0.0.0.0" # bind all interfaces so the host can reach it
NEO4J_MCP_HTTP_PORT: "8000" # must be >1024 (container runs as non-root)volumes:
neo4j_data:
Здесь два момента заслуживают внимания.
- Транспорт HTTP вместо stdio. Курс запускает сервер в режиме stdio, при котором хост запускает его как дочерний процесс. В данном случае сервер работает как независимая HTTP-служба, что ближе к реальной среде развертывания и позволяет любому клиенту подключаться по URL.
- Почему именно эти значения. Контейнер не имеет прав root, поэтому попытка привязать привилегированный порт ниже 1024 проваливается. По этой причине вместо порта 80 используется порт 8000. В режиме HTTP сервер по замыслу также отклоняет переменные окружения
NEO4J_USERNAMEиNEO4J_PASSWORD. Учетные данные передаются с каждым запросом с использованием метода HTTP Basic Auth, что соответствует модели аутентификации в производственной среде, поэтому эти переменные не используются.
Шаг 2: Запустить сервер
docker compose up -d --build
Во время первого запуска загружается образ Neo4j, компилируется сервер MCP на Go, а также загружаются плагины APOC и GDS. Через примерно минуту проверьте, что оба контейнера запущены:
docker compose ps
Подождите, пока neo4j сообщит (healthy).
Шаг 3: Проверка сервера
Эндпоинт MCP находится по адресу http://localhost:8000/mcp. При открытии его в браузере отображается сообщение Method Not Allowed: only POST is supported. Это на самом деле обнадёживает, поскольку означает, что сервер работает, а браузер просто отправил запрос типа GET.
Для корректного тестирования используйте curl. Сначала убедитесь, что включена аутентификация:
curl -i -X POST http://localhost:8000/mcp # expect 401 Unauthorized
Далее перечислите инструменты при аутентификации с использованием учетных данных базы данных:
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:8000/mcp
В ответе должны быть указаны get-schema, read-cypher и write-cypher.
Почему отображаются только три инструмента
В курсе описаны четыре инструмента, а отсутствующим является list-gds-procedures. Ничего не сломано. Этот инструмент регистрируется по мере необходимости во время процедуры инициализации MCP initialize, и только тогда, когда установлено Graph Data Science. Запрос tools/list без дополнительных параметров пропускает эту процедуру, поэтому четвертый инструмент так и не появляется. Сначала отправьте команду initialize, а затем снова запросите список инструментов:
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}},"id":1}' \
http://localhost:8000/mcp
curl -s -u neo4j:password123 -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":2}' \
http://localhost:8000/mcp
Теперь отображаются все четыре инструмента. Настоящие клиенты, такие как VS Code, выполняют initialize самостоятельно, поэтому эта особенность влияет только на прямые вызовы curl.
Шаг 4: Подключение к VS Code
Создайте файл .vscode/mcp.json в проекте:
{
"servers": {
"neo4j": {
"type": "http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Basic bmVvNGo6cGFzc3dvcmQxMjM="
}
}
}
}
Значение Authorization представляет собой просто кодирование neo4j:password123 в формате Base64. После смены пароля генерируйте его заново с помощью:
printf 'neo4j:yourpassword' | base64
Самая распространённая ошибка — повторное использование конфигурации stdio курса ("type": "stdio", "command": "neo4j-mcp") в данной настройке Docker. Это заставляет VS Code запускать локальный бинарник, который на самом деле отсутствует. Для сервера в контейнере требуется конфигурация http, показанная выше.
В VS Code откройте палитру команд с помощью Cmd/Ctrl + Shift + P, выполните команду MCP: List Servers, выберите neo4j и нажмите Start Server. Затем переключите режим чата в режим агента (Cmd/Ctrl + Shift + I) и запросите список доступных инструментов MCP с их идентификаторами и описаниями. Будут возвращены четыре инструмента.
Шаг 5: Применение
Локальная база данных изначально пуста, поэтому второй временный контейнер MCP может обращаться к публичной демо-базе данных Neo4j с примерами фильмов, той же, что используется в курсе, но через другой порт. Основная стек-структура остается нетронутой:
docker run --rm -d --name mcp-movies \
-e NEO4J_URI="neo4j+s://demo.neo4jlabs.com" \
-e NEO4J_DATABASE="recommendations" \
-e NEO4J_TRANSPORT_MODE="http" \
-e NEO4J_MCP_HTTP_HOST="0.0.0.0" \
-e NEO4J_MCP_HTTP_PORT="8001" \
-p 8001:8001 \
<your-project-name>-neo4j-mcp
Имя изображения — это то, что сгенерирует docker compose. Чтобы увидеть его, выполните команду docker images; ожидается результат вида yourfolder-neo4j-mcp.
Чтобы прочитать схему и узнать, какие связи имеет объект User, вызовите функцию read-cypher:
curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (u:User)-[r]->() RETURN DISTINCT type(r) AS rel"}},"id":2}' \
http://localhost:8001/mcp
Ответ — RATED, что означает (:User)-[:RATED]->(:Movie).
Чтобы сгенерировать запрос к фильму с самой высокой оценкой, необходимо использовать проверку на наличие значения, поскольку не у каждого фильма есть оценка:
curl -s -u recommendations:recommendations -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"read-cypher","arguments":{"query":"MATCH (m:Movie) WHERE m.imdbRating IS NOT NULL RETURN m.title AS title, m.imdbRating AS rating ORDER BY m.imdbRating DESC LIMIT 1"}},"id":3}' \
http://localhost:8001/mcp
Когда демонстрация завершится, остановите контейнер:
docker stop mcp-movies
Шаг 6: Небольшое приложение сверху
Курс завершается тем, что учащиеся создают инструмент командной строки на Python, который возвращает пять лучших фильмов определённого жанра. В этой упрощённой версии жанр передаётся как параметр запроса, а не путём объединения строк, причём исключаются нулевые оценки:
import os, sys
from neo4j import GraphDatabase
QUERY = """
MATCH (m:Movie)-[:IN_GENRE]->(:Genre {name: $genre})
WHERE m.imdbRating IS NOT NULL
RETURN m.title AS title, m.imdbRating AS rating
ORDER BY m.imdbRating DESC
LIMIT 5
"""def main():
uri = os.environ["NEO4J_URI"]
user = os.environ["NEO4J_USERNAME"]
pwd = os.environ["NEO4J_PASSWORD"]
db = os.environ.get("NEO4J_DATABASE", "neo4j") genre = input("Enter a movie genre: ").strip()
with GraphDatabase.driver(uri, auth=(user, pwd)) as driver:
driver.verify_connectivity()
records, _, _ = driver.execute_query(QUERY, genre=genre, database_=db) print(f"\nTop {len(records)} '{genre}' movies:")
for i, r in enumerate(records, 1):
print(f" {i}. {r['title']} ({r['rating']})")if __name__ == "__main__":
main()
Запустите его на демо-базе данных:
pip install neo4j
export NEO4J_URI="neo4j+s://demo.neo4jlabs.com"
export NEO4J_USERNAME="recommendations"
export NEO4J_PASSWORD="recommendations"
export NEO4J_DATABASE="recommendations"
python3 movie_recommender.py # then type: Mystery
Что было достигнуто
Примерно за полчаса полная стек-сборка Neo4j MCP запустилась локально без использования Codespaces и без дополнительных расходов в облаке:
- Neo4j с APOC и GDS, а также официальный сервер
neo4j-mcp, оба в формате Docker - Сервер MCP в качестве аутентифицированного HTTP-сервиса
- VS Code, подключенный в режиме Agent
- Реальные запросы через инструменты MCP и небольшое приложение на Python
Почему самостоятельное хостинг обучает лучше
Можно легко воспринять это как способ обойти ограничения, но личный запуск сервера показывает нечто гораздо более полезное. MCP превращается в стандартный способ для ИИ-агентов взаимодействовать с реальными системами: базами данных, API и внутренними инструментами. Именно здесь возникают интересные инженерные вопросы: как передается сервер? Как аутентифицируются запросы? Что предотвращает выполнение агентом разрушительных запросов?
Работа сервера через HTTP с аутентификацией на уровне каждого запроса и режимом только для чтения выдвигает эти вопросы на поверхность, тогда как готовая хостинговая среда скрывает их. Поскольку агенты всё чаще используются для работы с реальными производственными данными, запуск сервера MCP в качестве контролируемого и отслеживаемого сервиса имеет большее значение, чем доверие к «черному ящику», хостинг которого осуществляет кто-то другой. Та же логика применима и к реальной развертке за шлюзом с TLS и менеджером секретов.
Устранение неполадок
Method Not Allowedв браузере: запрос был типа GET, в то время как конечная точка принимает только запросы типа POST. Используйте curl или клиент MCP.401 Unauthorized: отсутствует или неверна базовая аутентификация. Используйте имя пользователя и пароль из базы данных.- Перечислено только три инструмента: сначала отправьте команду
initializeи убедитесь, что установлены APOC и GDS.
get-schema не работает: установлен APOC. Добавьте его в NEO4J_PLUGINS.NEO4J_USERNAME или NEO4J_PASSWORD были заданы в режиме HTTP. Удалите их оба.mcp.json всё ещё сохранена конфигурация stdio. Используйте конфигурацию для режима http.NEO4J_MCP_HTTP_PORT превышает 1024, поскольку контейнер не имеет прав root.Дополнительная литература
В документации сервера Neo4j MCP и в официальной спецификации MCP приведены подробные сведения.
Связанная литература
- Защита сервера Spring AI MCP с использованием OAuth 2.0 и диапазонов доступа для отдельных инструментов — Создание сервера авторизации OAuth и преобразование сервера Spring AI MCP в сервер ресурсов, тестирование в MCP Inspector, а затем ограничение доступа к отдельным инструментам с помощью диапазонов.
- Практические заметки: Microsoft создала сервер Playwright MCP, а затем сказала вам, что делать — Пошаговое руководство по практическим заметкам: Microsoft создала сервер Playwright MCP, а затем сказала вам, что делать: контракты, проверки и готовые блоки кода для команд, использующих эту схему.