Gel Database MCP server

The Gel Database MCP Server implements the Model Context Protocol for streamlined interaction with EdgeQL and Gel databases. It enables LLM agents (like Cursor Agent or Claude Code) to explore your database schema, validate queries, and execute EdgeQL commands through natural language.

Quick Start Guide

Installation

# 1. Install dependencies
yarn install

# 2. Copy your dbschema folder into the project if you have one already 

# 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

# 4. Generate EdgeQL JavaScript query builder files
npx @gel/generate edgeql-js
# Note: 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. Test the server runs without errors
node build/index.js

# 7.1 (if you have errors) Test server with a UI that provides more clear error logs
npx @modelcontextprotocol/inspector node build/index.js

Connecting to 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

Available Tools

describe-schema

This tool helps your LLM agent learn and understand your database structure without manual inspection. The agent can discover available entity types, their properties, relationships, and constraints.

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

validate-query

Allows your LLM agent to verify raw EdgeQL query syntax without execution, providing safe validation of generated queries.

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

execute-edgeql

Enables your LLM agent to directly interact with your database by running raw EdgeQL queries, retrieving data, and performing operations based on your instructions.

Example:

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

search-gel-docs

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

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

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)

Note on Documentation: For optimal results, we recommend both:

1. Including the gel_llm.txt file in your project root (for direct file access)
2. Using the search-gel-docs tool for targeted queries

execute-typescript

Similar to execute-edgeql but can be used for testing and running Typescript Gel queries made with the query builder syntax.

Best practices:

• 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 that require programmatic logic or when you need to process query results with JavaScript.

Learn More

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "gel-database" '{"command":"node","args":["build/index.js"]}'

See the official Claude Code MCP documentation for more details.

For 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 > Tools & Integrations and click "New MCP Server".

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

{
    "mcpServers": {
        "gel-database": {
            "command": "node",
            "args": [
                "build/index.js"
            ]
        }
    }
}

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 explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "gel-database": {
            "command": "node",
            "args": [
                "build/index.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect