Gel Database MCP server

The Gel Database MCP Server is a TypeScript-based implementation of the Model Context Protocol that connects large language models with your Gel database. It enables AI agents (like Cursor Agent or Claude Code) to understand your database schema, validate EdgeQL queries, and execute database operations through natural language instructions.

Installation

Prerequisites

• Node.js and yarn installed
• A Gel database instance (existing or new)

Setup Steps

# Install dependencies
yarn install

# Copy your existing dbschema folder into the project (if you have one)
# cp -r /path/to/your/dbschema ./

# Initialize a Gel project
npx gel project init
# Follow the prompts to set up a new project or connect to an existing instance

# Generate EdgeQL JavaScript query builder files
npx @gel/generate edgeql-js
# Remember to re-run this after any schema changes

Configuration

1. Update the database connection settings in src/index_gel.ts:

   • Edit lines 19-25 with your database credentials (database name, host, port, user, password)
   • Edit line 37 with your branch name

2. Build the project:

   yarn build
   

3. Test the server:

   node build/index.js
   

   For better error logging, use:

   npx @modelcontextprotocol/inspector node build/index.js
   

4. (Recommended) Add the Gel documentation file:

   # Replace with the actual source URL
   curl -o gel_llm.txt https://raw.githubusercontent.com/yourorg/gel-docs/main/gel_llm.txt
   

Connecting to Cursor

1. Open Cursor and click on the gear icon in the top right
2. Navigate to MCP > +Add a new server
3. Name your server
4. Select type: Command
5. Enter: node your/full/path/to/build/index.js

Available Tools

describe-schema

Helps your AI agent understand your database structure without manual inspection. The agent can discover entity types, properties, relationships, and constraints.

When to use: When the agent needs to understand database structure before creating queries.

validate-query

Allows the AI agent to verify EdgeQL query syntax without execution, providing safe validation before running against your database.

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

execute-edgeql

Enables the AI agent to directly interact with your database by running raw EdgeQL queries based on your instructions.

Example:

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

search-gel-docs

Allows the AI agent to search through Gel documentation to find information about EdgeQL syntax, features, or examples.

Example parameters:

search_term: "for loop"
context_lines: 10  # Optional: default is 5
match_all_terms: true  # Optional: default is false

Best practice: Use both the bundled gel_llm.txt file and this search tool for optimal results.

execute-typescript

Provides the ability to run TypeScript Gel queries using the query builder syntax.

Best practices:

• Use await gelClient.query() with console.log to display results
• Use ORDER BY with THEN syntax (e.g., ORDER BY .field1 THEN .field2)
• Keep code 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 when processing query results with JavaScript.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.