Запуск MCP-сервера Neo4j на сваёй машыне з Docker і VS Code
Разгортваем Neo4j і яго афіцыйны MCP-сервер праз Docker Compose, абараняем Basic Auth па HTTP, падключаем VS Code у рэжыме агента і робім запыты да дэма-графа.
Крыніцы: Run the Neo4j MCP Server Locally with Docker (No Codespaces Needed)
Афіцыйны сервер MCP ад Neo4j — гэта маленькая програма, і весь стак можа запрацаваць на ноутбуку з Docker прыблізна за паўгадзіны. Гэта мае значэнне для тых, хто выкананае курс GraphAcademy па разработцы з інструментамі MCP ад Neo4j, таму што курс выкорыстоўвае GitHub Codespaces, а у 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, скомпілюе сервер 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. Нічога не зламана. эты інструмент рэгіструецца пасляўльна пад час працэсу 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. Пасля чаго пераключыце рэжым чату на рэжым агента (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
Што было аджынято
За прыблызу паўгадзіны весь стак MCP для Neo4j працуе локальна без Codespaces і без дагадкі за выкарыстоўванне хмарных сервісаў:
- Neo4j з APOC і GDS, а таксама офіцыйны сервер
neo4j-mcp, оба ў Docker - Сервер MCP як аўтэнтыфікованы HTTP-сервіс
- VS Code, падключаны ў рэжыме Agent
- Рэальныя запыткі праз інструменты MCP і невялікі Python-дапрыемак
Чаму самастойнае хоставанне дапамагае больш навучыцца
Можна было б спачатку прыйняць гэта за спосаб абіецца ад квот, але лічыцца, што персональная праца сервера паказвае ўсё бол корыстныя рэчы. MCP стае стандартным спосабам для AI-агентаў прабівацца да рэальных сістэм: баз дадзенаў, 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. А потым сказаў вам: контракты, перакананні і месцы для коду для команд, якія вікорыстоўваюць гэты патэрн.