📌Overview

Purpose: To streamline Gel database operations using EdgeQL queries through a TypeScript-based Model Context Protocol (MCP) server.

Overview: The Gel Database MCP Server simplifies interactions with Gel databases by allowing LLM agents to automate learning about the database schema, as well as writing, validating, and executing database queries in a user-friendly manner.

Key Features:

• describe-schema: Enables LLM agents to automatically understand database structures, identifying entity types, properties, and relationships, which helps them generate accurate queries.

• validate-query: Allows LLM agents to verify the syntax of raw EdgeQL queries without executing them, ensuring safe query development without risks.

• execute-edgeql: Empowers LLM agents to run raw EdgeQL queries directly, enabling them to retrieve and manipulate data as per user instructions.

• search-gel-docs: Facilitates the search of Gel documentation, allowing LLM agents to quickly find relevant information about EdgeQL syntax and features for better execution of database operations.

• execute-typescript: Similar to execute-edgeql, but designed for running Typescript queries using a query builder syntax, enhancing flexibility for complex queries and programmatic processing.

---

Gel Database MCP Server

A TypeScript-based Model Context Protocol (MCP) server designed to streamline Gel database operations with EdgeQL queries. This project provides tools for LLM Agents (Cursor Agent, Claude Code, etc.) to automate learning about your schema, and writing, validating, and executing database queries. Easily interact with your Gel database through natural language.

Note: Query generation is not included since LLMs can write more flexible queries. Tested with Cursor agent using Claude-3.7-sonnet-thinking and had good results after providing Gel docs by linking relevant webpages.

---

Quick Start Guide

# 1. Install dependencies
yarn install

# 2. Copy your dbschema folder into the project if you have one already 
# cp -r /path/to/your/dbschema ./
# or just copy and paste

# 3. Initialize a Gel project
npx gel project init
# Follow prompts to set up a new project 
# Can point to an existing gel instance by providing the name of your instance
#   - Import migrations if it asks

# 4. Generate EdgeQL JavaScript query builder files
npx @gel/generate edgeql-js
# Re-run this command after any schema changes

# 5. Update connection settings
# Edit src/index_gel.ts lines 19-25 with your database, host, port, user, password
# Edit src/index_gel.ts line 37 with your branch name

# 6. Build the project
yarn build

# 7. (Optional) Test the server runs without errors
node build/index.js

# 7.1 (If you have errors) Test server with a UI for clearer error logs:
npx @modelcontextprotocol/inspector node build/index.js

# 8. (Recommended) Include the gel_llm.txt documentation file
# Download the Gel documentation file and place it in your project root to allow both the search tool and direct file access for your LLM agent
# curl -o gel_llm.txt https://raw.githubusercontent.com/yourorg/gel-docs/main/gel_llm.txt
# Replace URL with the actual source of your gel_llm.txt file

---

Connect MCP Server in Cursor

1. Click on the gear icon on the top right > MCP > +Add a new server
2. Name it whatever you want
3. Select type: Command
4. Enter this: node your/full/path/to/build/index.js

Note: While primarily tested with Cursor's agent, it should work with other agents and LLMs supporting the Model Context Protocol. Contributions with findings from other agents are welcome.

---

Available Tools

The Gel Database MCP Server provides the following tools:

describe-schema

Helps your LLM agent learn and understand your database structure without manually inspecting the code. The agent discovers available entity types, their properties, relationships, and constraints to generate more accurate queries.

• When to use: When your agent needs to understand the structure of a database entity before querying it.

validate-query

Helps your LLM agent verify raw EdgeQL query syntax without executing it, allowing safe validation before running queries against your database.

• When to use: During query development to check syntax without risking execution side effects.

execute-edgeql

Allows your LLM agent to directly interact with your database by running raw EdgeQL queries, retrieving data, and performing operations autonomously.

Example:

SELECT Product { name, price } FILTER .price > 100;

search-gel-docs

Allows your LLM agent to search through Gel documentation to find relevant information about EdgeQL syntax, features, or examples. Returns comprehensive context to help the agent understand Gel database concepts.

• When to use: When your agent needs to learn about specific Gel/EdgeQL features, understand syntax, or find examples for database operations.

Example:

search_term: "for loop"
context_lines: 10  # Optional: Number of context lines to show (default: 5)
match_all_terms: true  # Optional: Require all terms to match (default: false)

Documentation Hybrid Approach: For optimal results, use both:

1. Include the gel_llm.txt file in your project root (for direct file access)
2. Use the search-gel-docs tool for targeted queries
   This approach gives your LLM agent flexibility in searching specific terms and accessing full documentation for broader context.

execute-typescript

Similar to execute-edgeql but for testing and running TypeScript Gel queries made with the query builder syntax.

• Instructions are included in the tool, but it's recommended to ask the agent what instructions it has so it loads them in context.
• Note: JavaScript syntax errors can crash the server. If the connection appears closed, refresh or restart the server.

Best practices for LLM:

• Use await gelClient.query() with console.log to display results
• Use ORDER BY with THEN, not commas (e.g., ORDER BY .field1 THEN .field2)
• Keep code simple and focused on a single operation

Example:

console.log(await gelClient.query(`
  SELECT Product { 
    name, 
    price 
  } 
  FILTER .price > 100 
  ORDER BY .price DESC 
  LIMIT 5;
`));

• When to use: For complex queries requiring programmatic logic or processing results with JavaScript.

---

Learn More

For more information about the Model Context Protocol, visit:
https://modelcontextprotocol.io/quickstart