FalkorDB

Consulta e interactúa con bases de datos gráficas de FalkorDB usando modelos de IA.

GitHub
41

Documentación

MCP Toplist

Tests codecov License Discord X (formerly Twitter) MCP Compatible

Servidor MCP de FalkorDB

Try Free

Un servidor de Protocolo de Contexto de Modelo (MCP) para FalkorDB, que permite a los modelos de IA consultar e interactuar con bases de datos de grafos. El Servidor MCP de FalkorDB permite que asistentes de IA como Claude interactúen con bases de datos de grafos FalkorDB usando lenguaje natural. Consulta tus datos de grafos, crea relaciones y gestiona tu grafo de conocimiento, todo a través de IA conversacional.

🎯 ¿Qué es esto?

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), permitiendo que los modelos de IA puedan:

  • Consultar bases de datos de grafos usando OpenCypher (con soporte de modo solo lectura)
  • Crear y gestionar nodos y relaciones
  • Listar y explorar múltiples grafos
  • Eliminar grafos cuando sea necesario
  • Consultas de solo lectura para instancias réplica o para prevenir escrituras accidentales

🚀 Inicio Rápido

Requisitos previos

  • Node.js 18+
  • Instancia de FalkorDB (ejecutándose local o remotamente)
  • Aplicación Claude Desktop (para integración con IA)

Ejecución desde npm

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Ejecución con npx

Puedes ejecutar el servidor directamente desde la línea de comandos usando npx:

Usando variables de entorno en línea:

# 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 un archivo .env:

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

Esto es útil para:

  • Pruebas rápidas y desarrollo
  • Ejecutar el servidor de forma independiente sin Claude Desktop
  • Integraciones personalizadas y scripting

Docker Compose

Ejecuta FalkorDB y el servidor MCP juntos:

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

Nota: Omitir el archivo .env deja variables como MCP_API_KEY y FALKORDB_PASSWORD vacías, lo que desactiva la autenticación con clave API y no usa contraseña de base de datos.

Esto inicia FalkorDB con comprobaciones de salud y volúmenes persistentes, además del servidor MCP preconfigurado para conectarse a él.

El servidor MCP se ejecuta en modo transporte HTTP y está expuesto en localhost:8080 por defecto. Para conectar un cliente, configúralo para usar:

  • Transporte: http
  • URL: http://localhost:8080
  • Clave API: Configurada mediante la variable de entorno MCP_API_KEY (opcional)

Consulta docker-compose.yml para el puerto exacto y los valores de configuración.

Instalación

  1. Clonar e instalar:

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

  2. Configurar el entorno:

    cp .env.example .env

    Edita .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. Compilar el proyecto:

    npm run build

🤖 Integración con Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Reinicia Claude Desktop y ¡verás las herramientas de FalkorDB disponibles!

📚 Herramientas MCP Disponibles

Una vez conectado, puedes pedirle a Claude que:

🔍 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: La herramienta query_graph ahora admite un parámetro readOnly para ejecutar consultas en modo solo lectura usando GRAPH.RO_QUERY. Esto es ideal para:

  • Ejecutar consultas en instancias réplica
  • Prevenir operaciones de escritura accidentales
  • Garantizar la integridad de los datos en entornos de producción

También hay una herramienta dedicada query_graph_readonly que siempre ejecuta consultas en modo solo lectura.

Consultas parametrizadas: Las herramientas query_graph y query_graph_readonly aceptan un objeto params opcional para que los valores se pasen por separado del texto de la consulta (referenciados como $name), en lugar de concatenarlos como cadenas en Cypher. Esto evita riesgos de inyección de consultas y consultas mal formadas. Por ejemplo, una consulta de MATCH (p:Person {name: $name}) RETURN p con params: { "name": "Alice" }. Los nombres de los parámetros (incluidas las claves de mapas anidados) deben ser identificadores válidos. Nota: FalkorDB no permite parámetros en cláusulas LIMIT/SKIP.

📝 Gestionar Datos

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

📊 Explorar Estructura

"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"

Descubrimiento de esquema: FalkorDB no tiene esquema, por lo que tres herramientas ayudan a un agente a orientarse antes de consultar:

  • get_graph_schema — devuelve etiquetas de nodos, tipos de relaciones y (opcionalmente) la topología de conexiones. Cada conexión es { source, relationship, target } donde source y target son arreglos de etiquetas de nodos (un nodo puede tener múltiples etiquetas) y relationship es el tipo de relación. La topología se deriva de una muestra limitada de relaciones (connectionSampleSize, por defecto 10000) y se puede desactivar con includeConnections: false en grafos muy grandes.
  • get_node_schema / get_relationship_schema — muestrean hasta sampleSize (por defecto 100) nodos/relaciones de una etiqueta/tipo dado y clasifican sus claves de propiedades por frecuencia, devolviendo el sampledCount real junto con requestedSampleSize. Útil para detectar desviaciones en la nomenclatura de propiedades.

Las tres herramientas de esquema siempre se ejecutan en modo solo lectura (GRAPH.RO_QUERY), por lo que son seguras de ejecutar contra implementaciones réplica/solo lectura.

Un flujo de trabajo típico de orientación es: list_graphs → get_graph_schema → get_node_schema / get_relationship_schema → query_graph.

🛠️ Desarrollo

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

Estructura del Proyecto

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

🔧 Configuración Avanzada

Modos de Transporte

El servidor admite dos modos de transporte:

stdio (por defecto)

Se usa para integración directa con clientes de IA como Claude Desktop. La comunicación ocurre mediante entrada/salida estándar.

MCP_TRANSPORT=stdio

HTTP Transmisible

Expone el servidor MCP sobre HTTP para acceso remoto o en red. Admite múltiples sesiones concurrentes mediante el protocolo MCP Streamable HTTP.

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

Al usar transporte HTTP, los clientes se conectan enviando una solicitud POST con un mensaje initialize. El servidor devuelve un encabezado Mcp-Session-Id que debe incluirse en solicitudes posteriores. La autenticación con clave API se aplica mediante el encabezado Authorization: Bearer <key> cuando MCP_API_KEY está configurado.

Prueba del transporte HTTP:

  1. Inicia el servidor:

    MCP_TRANSPORT=http MCP_PORT=8080 npm start

  2. Usa el Inspector MCP para conectarte:

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

Nota: npm run inspect usa transporte stdio. Para HTTP, inicia el servidor y el inspector por separado como se muestra arriba.

Autenticación con Clave API:

Cuando MCP_API_KEY está configurado, todas las solicitudes HTTP deben incluir un encabezado Authorization:

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

Los clientes deben enviar entonces:

Authorization: Bearer my-secret-key

Las solicitudes sin una clave válida reciben una respuesta 401 Unauthorized. La autenticación solo se aplica en modo HTTP — el modo stdio ignora MCP_API_KEY ya que solo el proceso padre puede comunicarse.

Uso con Docker

Usando imágenes precompiladas de 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

O úsalo con docker-compose junto a 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

Uso con FalkorDB Remoto

Para instancias de FalkorDB alojadas en la nube:

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

Modo Solo Lectura para Instancias Réplica

Si te conectas a una instancia réplica de FalkorDB o quieres garantizar que no se realicen operaciones de escritura, puedes habilitar el modo solo lectura por defecto:

FALKORDB_DEFAULT_READONLY=true

Esto hará que todas las consultas se ejecuten usando GRAPH.RO_QUERY por defecto. Aún puedes anular esto por consulta configurando el parámetro readOnly en la herramienta query_graph.

Casos de uso:

  • Instancias réplica: Previene escrituras en réplicas de lectura en configuraciones de replicación
  • Seguridad en producción: Garantiza que los datos críticos no se modifiquen accidentalmente
  • Informes/análisis: Ejecuta consultas para paneles sin riesgo de cambios en los datos
  • Entornos multiinquilino: Proporciona acceso de solo lectura a ciertos usuarios

Ejecución de Múltiples Instancias

Puedes ejecutar múltiples servidores MCP para diferentes instancias de 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"
      }
    }
  }
}

📖 Ejemplo de Uso

Esto es lo que puedes hacer una 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

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta nuestras Pautas de Contribución para más detalles.

Flujo de Trabajo de Desarrollo

  1. Haz un fork del repositorio
  2. Crea una rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios (git commit -m 'Add amazing feature')
  4. Sube a la rama (git push origin feature/amazing-feature)
  5. Abre una Solicitud de Extracción

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENCIA para más detalles.

🙏 Agradecimientos

🔗 Recursos

Hecho con ❤️ por el equipo de FalkorDB y Katie Mulliken