Neo4j MCP

Сервер протокола контекста модели (MCP), который позволяет Claude (и другим MCP-клиентам) выполнять запросы и изменять графовые базы данных Neo4j. Поставляется как автономный MCP-сервер и как плагин для Claude Code, который можно установить один раз и использовать повторно в любом проекте.

Каждый проект предоставляет свои учетные данные Neo4j через локальный файл .env, поэтому один и тот же плагин может работать с разными базами данных в зависимости от того, в какой папке открыт Claude Code.

Возможности

• Один консолидированный инструмент cypher_query с явным режимом read / write.

• Интроспекция схемы: метки, типы связей и ключи свойств.

• Полная сериализация результатов — сохраняет element_id узлов/связей, метки, типы и временные/пространственные значения Neo4j.

• Ограничение размера результата с флагом усечения, чтобы неконтролируемый MATCH (n) не переполнил ответ.

• Учетные данные для каждого проекта через .env (загружается с помощью python-dotenv из рабочей директории).

• Работает со stdio (Claude Code, Claude Desktop, Cursor) и SSE.

Related MCP server: neo4j-server-remote

Предварительные требования

• Python 3.10+

• Доступная база данных Neo4j (локальная, Docker или Aura)

• pip (или uv, pipx)

Установка Python-пакета

Плагин вызывает консольный скрипт под названием neo4j-mcp-server, поэтому пакет должен находиться в вашем PATH.

git clone https://github.com/your-repo/neo4j-mcp.git
cd neo4j-mcp
pip install -e .

Проверьте, что установка прошла успешно:

which neo4j-mcp-server
neo4j-mcp-server --help

Совет: если вы используете pipx, команда pipx install -e . изолирует сервер от вашего глобального Python.

Использование в качестве плагина Claude Code

Репозиторий содержит манифест плагина в .claude-plugin/plugin.json. После установки на уровне пользователя сервер neo4j MCP становится доступен в каждой сессии Claude Code, в любом проекте.

1. Установка плагина

Изнутри Claude Code:

/plugin install /absolute/path/to/neo4j-mcp

Это глобально регистрирует манифест. (Вы также можете добавить его через маркетплейс, если опубликуете свой — см. документацию по плагинам Claude Code.)

2. Добавьте .env в любой проект, который должен взаимодействовать с Neo4j

MCP-сервер наследует рабочую директорию Claude Code, поэтому python-dotenv считывает любой файл .env, находящийся в корне проекта. Разные папки → разные базы данных, перенастройка плагина не требуется.

# my-project/.env
NEO4J_HOST=localhost
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-secret
NEO4J_DATABASE=neo4j

Для Aura / зашифрованных соединений:

NEO4J_HOST=xxx.databases.neo4j.io
NEO4J_PORT=7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-aura-password
NEO4J_URI_SCHEME=neo4j+s
NEO4J_ENCRYPTED=true

Для неаутентифицированного локального экземпляра оставьте NEO4J_USERNAME и NEO4J_PASSWORD пустыми.

Не добавляйте .env в систему контроля версий. Добавьте его в .gitignore в каждом проекте.

3. Использование в Claude Code

Откройте проект и задавайте Claude вопросы, например:

• "Какие метки и типы связей существуют в этом графе?"

• "Найди 10 наиболее связанных узлов Person."

• "Создай узел Movie с названием Inception, выпущенный в 2010 году."

Claude будет вызывать инструменты cypher_query, get_database_schema и test_database_connection по мере необходимости.

Использование без Claude Code

Тот же пакет работает как обычный MCP-сервер для любого MCP-совместимого клиента.

Claude Desktop / Cursor

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или в конфигурацию MCP вашего Cursor:

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "args": []
    }
  }
}

Установите учетные данные, поместив файл .env рядом с местом, откуда клиент запускает процесс, или экспортировав переменные NEO4J_* в блоке окружения.

Транспорт SSE (веб-клиенты)

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

Автономный CLI

Небольшой клиент включен в комплект для разового тестирования:

neo4j-mcp-client --test
neo4j-mcp-client --schema
neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes"
neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

Справочник по конфигурации

Все настройки считываются из переменных окружения (или файла .env в рабочей директории).

Инструменты, предоставляемые MCP-сервером

Ресурсы: neo4j://schema, neo4j://connection. Промпт: cypher_query_help.

Разработка

pip install -e ".[dev]"
pytest                    # 21 unit tests, no live database needed
ruff check src/ tests/
mypy src/neo4j_mcp/

Устранение неполадок

• Neo4j authentication failed — неверное имя пользователя или пароль. Для БД без аутентификации оставьте оба поля пустыми (не устанавливайте их как neo4j/neo4j).

• Neo4j service unavailable — БД не работает или указаны неверные NEO4J_HOST / NEO4J_PORT. Попробуйте cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT для проверки.

• Плагин не может найти neo4j-mcp-server — консольный скрипт отсутствует в PATH, который наследует Claude Code. Установите с помощью pipx или убедитесь, что ваш shell rc-файл экспортирует правильный PATH для GUI-приложений. В macOS GUI-приложения не читают ~/.zshrc; используйте launchctl setenv PATH ... или установите в /usr/local/bin.

• truncated: true при чтении — увеличьте limit в вызове или установите более высокое значение NEO4J_DEFAULT_RESULT_LIMIT в .env.

Лицензия MIT.