Hasura GraphQL MCP server

This MCP server enables AI agents to interact with Hasura GraphQL endpoints, allowing them to discover API structure, execute queries and mutations, preview data, and perform aggregations - all based on natural language requests.

Installation Requirements

• Node.js v18 or higher
• pnpm (or npm/yarn)
• Access to a running Hasura GraphQL endpoint
• (Optional but recommended) Hasura Admin Secret

Installation Steps

Install Dependencies

pnpm install

Build the Server

pnpm run build

Running the Server

Execute the compiled script with your Hasura endpoint URL and optional admin secret:

# Using pnpm start script
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# Or using Node directly
node dist/index.js <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

Examples:

With admin secret:

pnpm start https://my-hasura.cloud/v1/graphql mysecretkey123

Without admin secret (using default role permissions):

pnpm start https://my-hasura.cloud/v1/graphql

Connecting to MCP Clients

Finding Required Paths

1. Node executable path: Run which node in your terminal
2. Server script path: Navigate to the project directory and run pwd, then append /dist/index.js
3. Project directory path: Use the output of pwd

Configuring for Cursor

Add the following to Cursor's settings.json:

{
  "cursor.customMcpServers": [
    {
      "name": "My Advanced Hasura Server",
      "command": "/path/to/your/node",
      "args": [
        "/absolute/path/to/mcp-hasura-advanced/dist/index.js",
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",
        "YOUR_ADMIN_SECRET"
      ],
      "cwd": "/absolute/path/to/mcp-hasura-advanced"
    }
  ]
}

Configuring for Claude Desktop

Add the following to Claude Desktop's claude_desktop_config.json:

{
    "mcpServers": {
        "hasura-advanced": {
            "command": "/path/to/your/node",
            "args": [
                "/absolute/path/to/mcp-hasura-advanced/dist/index.js",
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",
                "YOUR_ADMIN_SECRET"
            ]
        }
    }
}

Replace all placeholders with your actual values, save the configuration, and restart your MCP client application.

Available Capabilities

Resources

• Hasura GraphQL Schema - Provides the full GraphQL schema definition via introspection

Tools

• run_graphql_query - Executes read-only GraphQL queries
• run_graphql_mutation - Executes GraphQL mutations (use with caution)
• list_tables - Lists available data tables managed by Hasura
• describe_table - Shows the structure of a specific table
• list_root_fields - Lists top-level query, mutation, or subscription fields
• describe_graphql_type - Provides details about a specific GraphQL type
• preview_table_data - Fetches sample rows from a specified table
• aggregate_data - Performs simple aggregations (count, sum, avg, min, max)
• health_check - Verifies the Hasura endpoint is responding

Example Usage

After configuring your MCP client, you can interact with the server using natural language prompts:

• "List all tables in the database"
• "Describe the 'users' table"
• "Preview data from the 'orders' table"
• "Run the query { products { name price } }"
• "Count the number of users in the system"

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.