Запустіть сервер 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 з розробки інструментів на основі 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. Видаліть їх обидва.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. А потім сказав вам, що робити: контракти, перевірки та шаблони коду для команд, які використовують цю схему.