FalkorDB

Consulte e interaja com bancos de dados gráficos FalkorDB usando modelos de IA.

GitHub
41
Experimente este MCPPatrocinado

Documentação

MCP Toplist

Tests codecov License Discord X (formerly Twitter) MCP Compatible

Servidor MCP FalkorDB

Try Free

Um servidor Model Context Protocol (MCP) para FalkorDB, permitindo que modelos de IA consultem e interajam com bancos de dados de grafos. O Servidor MCP FalkorDB permite que assistentes de IA como o Claude interajam com bancos de dados de grafos FalkorDB usando linguagem natural. Consulte seus dados de grafo, crie relacionamentos e gerencie seu grafo de conhecimento — tudo por meio de IA conversacional.

🎯 O que é isso?

Este servidor implementa o Model Context Protocol (MCP), permitindo que modelos de IA:

  • Consultem bancos de dados de grafos usando OpenCypher (com suporte a modo somente leitura)
  • Criem e gerenciem nós e relacionamentos
  • Listem e explorem múltiplos grafos
  • Excluam grafos quando necessário
  • Consultas somente leitura para instâncias de réplica ou para evitar gravações acidentais

🚀 Início Rápido

Pré-requisitos

  • Node.js 18+
  • Instância FalkorDB (executando localmente ou remotamente)
  • Aplicativo Claude Desktop (para integração com IA)

Executando a partir do npm

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "falkordb": {
      "command": "npx",
      "args": [
        "-y",
        "@falkordb/mcpserver@latest"
      ],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "FALKORDB_USERNAME": "",
        "FALKORDB_PASSWORD": ""
      }
    }
  }
}

Executando com npx

Você pode executar o servidor diretamente da linha de comando usando npx:

Usando variáveis de ambiente inline:

# Run with stdio transport (default)
FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

# Run with HTTP transport
MCP_TRANSPORT=http MCP_PORT=3005 FALKORDB_HOST=localhost FALKORDB_PORT=6379 npx -y @falkordb/mcpserver

Usando um arquivo .env:

# Using dotenv-cli to load environment variables from .env
npx dotenv-cli -e .env -- npx @falkordb/mcpserver

Isso é útil para:

  • Testes rápidos e desenvolvimento
  • Executar o servidor de forma autônoma sem o Claude Desktop
  • Integrações personalizadas e scripts

Docker Compose

Execute FalkorDB e o servidor MCP juntos:

cp .env.example .env   # create env file; edit to set MCP_API_KEY, FALKORDB_PASSWORD, etc.
docker compose up -d

Nota: Pular o arquivo .env deixa variáveis como MCP_API_KEY e FALKORDB_PASSWORD vazias, o que desativa a autenticação por chave de API e não usa senha de banco de dados.

Dica: Defina REDIS_ARGS em .env para passar sinalizadores extras ao redis-server do FalkorDB incluído, por exemplo REDIS_ARGS=--appendonly yes. O valor é dividido por espaços em branco, e os sinalizadores de autenticação derivados de FALKORDB_PASSWORD são anexados depois, então eles vencem em caso de conflito.

Sinalizadores que gravam em disco ainda não sobrevivem a um docker compose down: a imagem executa redis-server --dir /var/lib/falkordb/data — anexado depois de REDIS_ARGS, então o diretório não pode ser substituído aqui — enquanto o volume falkordb-data é montado em /data. Até que #174 mova a montagem para o diretório de dados real, arquivos RDB e AOF são gravados na camada gravável do contêiner.

Isso inicia FalkorDB com verificações de integridade e volumes persistentes, além do servidor MCP pré-configurado para se conectar a ele.

O servidor MCP executa no modo transporte HTTP e é exposto em localhost:8080 por padrão. Para conectar um cliente, configure-o para usar:

  • Transporte: http
  • URL: http://localhost:8080
  • Chave de API: Definida pela variável de ambiente MCP_API_KEY (opcional)

Consulte docker-compose.yml para a porta exata e valores de configuração.

Instalação

  1. Clone e instale:

    git clone https://github.com/FalkorDB/FalkorDB-MCPServer.git
cd FalkorDB-MCPServer
npm install

  2. Configure o ambiente:

    cp .env.example .env

    Edite .env:

    # Environment Configuration
NODE_ENV=development

# FalkorDB Configuration
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=    # Optional
FALKORDB_PASSWORD=    # Optional
FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode (useful for replicas)

# Logging Configuration (optional)
ENABLE_FILE_LOGGING=false

  3. Compile o projeto:

    npm run build

🤖 Integração com Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "falkordb": {
      "command": "node",
      "args": [
        "/absolute/path/to/falkordb-mcpserver/dist/index.js"
      ]
    }
  }
}

Reinicie o Claude Desktop e você verá as ferramentas FalkorDB disponíveis!

📚 Ferramentas MCP Disponíveis

Uma vez conectado, você pode pedir ao Claude para:

🔍 Consultar Grafos

"Show me all people who know each other"
"Find the shortest path between two nodes"
"What relationships does John have?"
"Run a read-only query on the replica instance"

Nota: A ferramenta query_graph agora suporta um parâmetro readOnly para executar consultas em modo somente leitura usando GRAPH.RO_QUERY. Isso é ideal para:

  • Executar consultas em instâncias de réplica
  • Prevenir operações de gravação acidentais
  • Garantir integridade dos dados em ambientes de produção

Há também uma ferramenta dedicada query_graph_readonly que sempre executa consultas em modo somente leitura.

Consultas parametrizadas: As ferramentas query_graph e query_graph_readonly aceitam um objeto params opcional para que valores possam ser passados separadamente do texto da consulta (referenciados como $name), em vez de concatená-los como strings no Cypher. Isso evita riscos de injeção de consulta e consultas malformadas. Por exemplo, uma consulta de MATCH (p:Person {name: $name}) RETURN p com params: { "name": "Alice" }. Nomes de parâmetros (incluindo chaves de mapas aninhados) devem ser identificadores válidos. Nota: FalkorDB não permite parâmetros em cláusulas LIMIT/SKIP.

📝 Gerenciar Dados

"Create a new person named Alice who knows Bob"
"Add a 'WORKS_AT' relationship between Alice and TechCorp"

📊 Explorar Estrutura

"List all available graphs"
"Show me the schema of the movies graph"
"What properties do Person nodes usually have in the movies graph?"
"What properties are on ACTED_IN relationships in the movies graph?"
"Delete the old_test graph"

Descoberta de esquema: FalkorDB é sem esquema, então três ferramentas ajudam um agente a se orientar antes de consultar:

  • get_graph_schema — retorna rótulos de nós, tipos de relacionamento e (opcionalmente) a topologia de conexões. Cada conexão é { source, relationship, target } onde source e target são arrays de rótulos de nós (um nó pode ter múltiplos rótulos) e relationship é o tipo de relacionamento. A topologia é derivada de uma amostra limitada de relacionamentos (connectionSampleSize, padrão 10000) e pode ser desativada com includeConnections: false em grafos muito grandes.
  • get_node_schema / get_relationship_schema — amostram até sampleSize (padrão 100) nós/relacionamentos de um determinado rótulo/tipo e classificam suas chaves de propriedade por frequência, retornando os sampledCount reais junto com requestedSampleSize. Útil para detectar desvios na nomenclatura de propriedades.

Todas as três ferramentas de esquema sempre executam somente leitura (GRAPH.RO_QUERY), então são seguras para executar contra implantações de réplica/somente leitura.

Um fluxo de orientação típico é: list_graphs → get_graph_schema → get_node_schema / get_relationship_schema → query_graph.

🛠️ Desenvolvimento

Comandos

# Development with hot-reload
npm run dev

# Development with TypeScript execution (faster startup)
npm run dev:ts

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Lint code
npm run lint

# Lint and auto-fix issues
npm run lint:fix

# Build for production
npm run build

# Start production server
npm start

# Inspect MCP server with debugging tools
npm run inspect

# Clean build artifacts
npm run clean

# Full CI pipeline (test, lint, build)
npm run prepublish

Estrutura do Projeto

src/
├── index.ts                   # MCP server entry point
├── services/                  # Core business logic
│   ├── falkordb.service.ts   # FalkorDB operations
│   └── logger.service.ts     # Logging and MCP notifications
├── mcp/                      # MCP protocol implementations
│   ├── tools.ts             # MCP tool definitions
│   ├── resources.ts         # MCP resource definitions
│   └── prompts.ts           # MCP prompt definitions
├── errors/                   # Error handling framework
│   ├── AppError.ts          # Custom error classes
│   └── ErrorHandler.ts      # Global error handling
├── config/                   # Configuration management
│   └── index.ts             # Environment configuration
├── models/                   # TypeScript type definitions
│   ├── mcp.types.ts         # MCP protocol types
│   └── mcp-client-config.ts # Configuration models
└── utils/                    # Utility functions
    └── connection-parser.ts  # Connection string parsing

🔧 Configuração Avançada

Modos de Transporte

O servidor suporta dois modos de transporte:

stdio (padrão)

Usado para integração direta com clientes de IA como o Claude Desktop. A comunicação ocorre via entrada/saída padrão.

MCP_TRANSPORT=stdio

HTTP Streamable

Expõe o servidor MCP via HTTP para acesso remoto ou em rede. Suporta múltiplas sessões concorrentes via protocolo MCP Streamable HTTP.

MCP_TRANSPORT=http
MCP_PORT=8080
MCP_API_KEY=your-secret-api-key  # Optional but recommended

Ao usar transporte HTTP, os clientes se conectam enviando uma solicitação POST com uma mensagem initialize. O servidor retorna um cabeçalho Mcp-Session-Id que deve ser incluído nas solicitações subsequentes. A autenticação por chave de API é aplicada via cabeçalho Authorization: Bearer <key> quando MCP_API_KEY está definido.

Testando transporte HTTP:

  1. Inicie o servidor:

    MCP_TRANSPORT=http MCP_PORT=8080 npm start

  2. Use o MCP Inspector para conectar:

    npx @modelcontextprotocol/inspector --transport streamable-http --url http://localhost:8080

Nota: npm run inspect usa transporte stdio. Para HTTP, inicie o servidor e o inspector separadamente, como mostrado acima.

Autenticação por Chave de API:

Quando MCP_API_KEY está definido, todas as solicitações HTTP devem incluir um cabeçalho Authorization:

MCP_TRANSPORT=http MCP_API_KEY=my-secret-key npm start

Os clientes devem então enviar:

Authorization: Bearer my-secret-key

Solicitações sem uma chave válida recebem uma resposta 401 Unauthorized. A autenticação só é aplicada no modo HTTP — o modo stdio ignora MCP_API_KEY já que apenas o processo pai pode se comunicar.

Usando com Docker

Usando imagens pré-construídas do Docker Hub:

# Use the latest stable release
docker pull falkordb/mcpserver:latest
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb/mcpserver:latest

# Or use the edge version (latest main branch)
docker pull falkordb/mcpserver:edge

# Or pin to a specific version
docker pull falkordb/mcpserver:1.0.0

Compilando localmente:

docker build -t falkordb-mcpserver .
docker run -p 8080:8080 \
  -e FALKORDB_HOST=host.docker.internal \
  -e FALKORDB_PORT=6379 \
  -e MCP_API_KEY=your-secret-key \
  falkordb-mcpserver

Ou use com docker-compose junto com FalkorDB:

services:
  falkordb:
    image: falkordb/falkordb:latest
    ports:
      - "6379:6379"

  mcp-server:
    image: falkordb/mcpserver:latest  # or use 'build: .' to build locally
    ports:
      - "8080:8080"
    environment:
      - FALKORDB_HOST=falkordb
      - FALKORDB_PORT=6379
      - MCP_TRANSPORT=http
      - MCP_PORT=8080
      - MCP_API_KEY=your-secret-key
    depends_on:
      - falkordb

Usando com FalkorDB Remoto

Para instâncias FalkorDB hospedadas na nuvem:

FALKORDB_HOST=your-instance.falkordb.com
FALKORDB_PORT=6379
FALKORDB_USERNAME=your-username
FALKORDB_PASSWORD=your-secure-password

Modo Somente Leitura para Instâncias de Réplica

Se você está se conectando a uma instância de réplica FalkorDB ou deseja garantir que nenhuma operação de gravação seja realizada, você pode habilitar o modo somente leitura por padrão:

FALKORDB_DEFAULT_READONLY=true

Isso fará com que todas as consultas sejam executadas usando GRAPH.RO_QUERY por padrão. Você ainda pode substituir isso por consulta, definindo o parâmetro readOnly na ferramenta query_graph.

Casos de uso:

  • Instâncias de réplica: Evite gravações em réplicas de leitura em configurações de replicação
  • Segurança em produção: Garanta que dados críticos não sejam modificados acidentalmente
  • Relatórios/análises: Execute consultas para painéis sem risco de alterações de dados
  • Ambientes multi-tenant: Forneça acesso somente leitura a certos usuários

Executando Múltiplas Instâncias

Você pode executar múltiplos servidores MCP para diferentes instâncias FalkorDB:

{
  "mcpServers": {
    "falkordb-dev": {
      "command": "node",
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "dev.falkordb.local",
        "FALKORDB_DEFAULT_READONLY": "false"
      }
    },
    "falkordb-prod-replica": {
      "command": "node", 
      "args": ["path/to/server/dist/index.js"],
      "env": {
        "FALKORDB_HOST": "replica.falkordb.com",
        "FALKORDB_DEFAULT_READONLY": "true"
      }
    }
  }
}

📖 Exemplo de Uso

Aqui está o que você pode fazer uma vez conectado:

// Claude can help you write queries like:
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.name = 'Alice'
RETURN friend.name, friend.age

// Or create complex data structures:
CREATE (alice:Person {name: 'Alice', age: 30})
CREATE (bob:Person {name: 'Bob', age: 25})
CREATE (alice)-[:KNOWS {since: 2020}]->(bob)

// And even analyze your graph:
MATCH path = shortestPath((start:Person)-[*]-(end:Person))
WHERE start.name = 'Alice' AND end.name = 'Charlie'
RETURN path

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes.

Fluxo de Trabalho de Desenvolvimento

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

📝 Licença

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

🔗 Recursos

Feito com ❤️ pela equipe FalkorDB e Katie Mulliken