Галоўная / Артыкулы

Запуск MCP-сервера Neo4j на сваёй машыне з Docker і VS Code

Разгортваем Neo4j і яго афіцыйны MCP-сервер праз Docker Compose, абараняем Basic Auth па HTTP, падключаем VS Code у рэжыме агента і робім запыты да дэма-графа.

Выдавец: REACTAPP.TOP8 хв чытання1743 слоў

Крыніцы: 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. Адзёрвіце іх оба.
  • 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, сортавання і ведэння журналу змян.