Головна / Статті

Запустіть сервер 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 з розробки інструментів на основі Neo4j MCP, адже курс передбачає використання 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 зазнає невдачі. Саме тому використовується порт 8000 замість 80. У режимі HTTP сервер також за замислом відхиляє змінні середовища NEO4J_USERNAME та NEO4J_PASSWORD. Облікові дані надсилаються з кожним запитом через HTTP Basic Auth, що відповідає моделі автентифікації в продакшені, тому ці змінні не використовуються.

Крок 2: Запустити його

docker compose up -d --build

Під час першого запуску завантажується образ Neo4j, компілюється сервер Go MCP та завантажуються плагіни 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. Нічого не зламано. Цей інструмент реєструється з відстрочкою під час процедури initialize MCP, і лише тоді, коли встановлена 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. Далі переключіть режим Chat у режим Agent (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, який повертає п’ять найкращих фільмів певного жанру. У цій спрощеній версії жанр передається як параметр запиту, а не шляхом об’єднання рядків, крім того відфільтровуються значення оцінок типу null:

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, протестуйте його та використовуйте для перегляду PR, сортування та створення журналів змін.