Neo4j

Neo4j MCP

Um servidor Model Context Protocol que permite ao Claude (e outros clientes MCP) consultar e modificar bancos de dados de grafos Neo4j. É distribuído tanto como um servidor MCP autônomo quanto como um plugin do Claude Code que você pode instalar uma vez e reutilizar em qualquer projeto.

Cada projeto fornece suas próprias credenciais Neo4j por meio de um arquivo .env local, para que o mesmo plugin possa ser direcionado a diferentes bancos de dados, dependendo da pasta em que o Claude Code é aberto.

---

Recursos

• Uma ferramenta cypher_query consolidada com modo read / write explícito.
• Introspecção de esquema: rótulos, tipos de relacionamento e chaves de propriedade.
• Serialização completa de resultados — preserva element_id de nós/relacionamentos, rótulos, tipos e valores temporais/espaciais do Neo4j.
• Proteção de tamanho de resultado com sinalizador de truncamento, para que um MATCH (n) descontrolado não estoure a resposta.
• Credenciais por projeto por meio de .env (carregado por python-dotenv a partir do diretório de trabalho).
• Funciona com stdio (Claude Code, Claude Desktop, Cursor) e SSE.

Pré-requisitos

• Python 3.10+
• Um banco de dados Neo4j acessível (local, Docker ou Aura)
• pip (ou uv, pipx)

Instalar o pacote Python

O plugin chama um script de console chamado neo4j-mcp-server, então o pacote precisa estar no seu PATH primeiro.

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

Verifique se foi instalado:

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

Dica: se você usa pipx, o pipx install -e . mantém o servidor isolado do seu Python global.

Usar como plugin do Claude Code

O repositório inclui um manifesto de plugin em .claude-plugin/plugin.json. Uma vez instalado no nível do usuário, o servidor MCP neo4j fica disponível em todas as sessões do Claude Code, em qualquer projeto.

1. Instalar o plugin

De dentro do Claude Code:

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

Isso registra o manifesto globalmente. (Você também pode adicioná-lo por meio de um marketplace, se publicar um — consulte a documentação de plugins do Claude Code.)

2. Coloque um .env em qualquer projeto que deva falar com o Neo4j

O servidor MCP herda o diretório de trabalho do Claude Code, então o python-dotenv captura qualquer .env que esteja na raiz daquele projeto. Pastas diferentes → bancos de dados diferentes, sem necessidade de reconfigurar o plugin.

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

Para Aura / conexões criptografadas:

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

Para uma instância local sem autenticação, deixe NEO4J_USERNAME e NEO4J_PASSWORD em branco.

Não faça commit do .env. Adicione-o ao .gitignore em todos os projetos.

3. Usar no Claude Code

Abra o projeto e pergunte ao Claude coisas como:

• "Quais rótulos e tipos de relacionamento existem neste grafo?"
• "Encontre os 10 nós Person mais conectados."
• "Crie um nó Movie intitulado Inception lançado em 2010."

O Claude chamará as ferramentas cypher_query, get_database_schema e test_database_connection conforme necessário.

Usar sem o Claude Code

O mesmo pacote funciona como um servidor MCP comum para qualquer cliente compatível com MCP.

Claude Desktop / Cursor

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou à sua configuração MCP do Cursor:

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

Defina as credenciais colocando um .env ao lado de onde o cliente inicia o processo, ou exportando variáveis NEO4J_* no bloco de ambiente.

Transporte SSE (clientes web)

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

CLI autônoma

Um pequeno cliente é incluído para testes pontuais:

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"

Referência de configuração

Todas as configurações são lidas de variáveis de ambiente (ou de um arquivo .env no diretório de trabalho).

Variável	Padrão	Descrição
NEO4J_HOST	localhost	Host Bolt
NEO4J_PORT	7687	Porta Bolt
NEO4J_HTTP_PORT	7474	Porta do navegador/HTTP (informativa)
NEO4J_USERNAME	(vazio)	Deixe em branco para bancos de dados sem autenticação
NEO4J_PASSWORD	(vazio)
NEO4J_DATABASE	neo4j	Banco de dados padrão
NEO4J_URI_SCHEME	bolt	Um de bolt, bolt+s, neo4j, neo4j+s
NEO4J_ENCRYPTED	false	Defina true para Aura / TLS
NEO4J_DEFAULT_RESULT_LIMIT	100	Limite de linhas para consultas de leitura quando nenhum é fornecido
NEO4J_MAX_CONNECTION_POOL_SIZE	100	Tamanho do pool do driver
NEO4J_CONNECTION_TIMEOUT	30.0	Segundos

Ferramentas expostas pelo servidor MCP

Ferramenta	Finalidade
cypher_query(query, mode="read"|"write", parameters?, database?, limit?)	Executa qualquer consulta Cypher. Use mode="write" para CREATE / MERGE / SET / DELETE, mesmo que você também RETURN linhas. Retorna {records, record_count, truncated, stats}.
get_database_schema(database?)	Retorna rótulos, tipos de relacionamento e chaves de propriedade.
test_database_connection()	Verifica a conectividade, retorna a string do agente do servidor e a versão do protocolo Bolt.

Recursos: neo4j://schema, neo4j://connection. Prompt: cypher_query_help.

Desenvolvimento

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

Solução de problemas

• Neo4j authentication failed — incompatibilidade de usuário/senha. Para bancos de dados sem autenticação, deixe ambos em branco (não os defina como neo4j / neo4j).
• Neo4j service unavailable — o banco de dados está fora do ar ou NEO4J_HOST / NEO4J_PORT estão errados. Tente cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT para confirmar.
• O plugin não encontra neo4j-mcp-server — o script de console não está no PATH que o Claude Code herda. Instale com pipx ou certifique-se de que o arquivo rc do seu shell exporta o PATH correto para aplicativos GUI. No macOS, aplicativos GUI não leem ~/.zshrc; use launchctl setenv PATH ... ou instale em /usr/local/bin.
• truncated: true em uma leitura — aumente limit na chamada, ou defina NEO4J_DEFAULT_RESULT_LIMIT mais alto em .env.

---

Licenciado sob MIT.