Главная / Статьи

Запустите сервер MCP Neo4j на собственном компьютере с помощью Docker и VS Code

Установите Neo4j и его официальный сервер MCP самостоятельно с помощью Docker Compose, защитите их с помощью базовой аутентификации через HTTP, подключите VS Code в режиме Agent и выполните запрос к демонстрационной графе.

Издатель: REACTAPP.TOP8 мин чтения1743 слов

Источники: 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. Удалите их оба.
  • VS Code сообщает, что сервер «требует взаимодействия для запуска»: в файле mcp.json всё ещё сохранена конфигурация stdio. Используйте конфигурацию для режима http.
  • Отклонено разрешение при привязке порта: убедитесь, что значение NEO4J_MCP_HTTP_PORT превышает 1024, поскольку контейнер не имеет прав root.
  • Дополнительная литература

    В документации сервера Neo4j MCP и в официальной спецификации MCP приведены подробные сведения.

    Связанная литература

  • Подключение частных репозиториев GitHub к Claude Desktop с использованием токена и Docker — Создайте классический токен GitHub с безопасными диапазонами полномочий, добавьте сервер GitHub MCP в Claude Desktop через Docker, протестируйте его и используйте для рассмотрения патчей, сортировки задач и ведения журналов изменений.