Advanced Hasura GraphQL MCP Server

Version: 1.1.0

This Model Context Protocol (MCP) server provides an advanced interface for AI agents (like those in Cursor or Claude Desktop) to interact with a Hasura GraphQL endpoint. It enables agents to discover the API structure, execute both read-only queries and mutations (with caution), preview data, perform aggregations, and check service health.

This server enhances LLM capabilities by allowing them to leverage your Hasura API dynamically based on natural language requests.

Features

This server exposes the following MCP capabilities:

Resources:

• Hasura GraphQL Schema (`hasura:/schema`)

Tools:

• `run_graphql_query`

• `run_graphql_mutation`

• `list_tables`

• `describe_table`

• `list_root_fields`

• `describe_graphql_type`

• `preview_table_data`

• `aggregate_data`

• `health_check`

Requirements

• Node.js (v18 or higher recommended, check `.nvmrc` or `package.json engines` if specified)
• `pnpm` (or `npm`/`yarn`, adjust commands accordingly)
• Access to a running Hasura GraphQL endpoint.
• (Optional but recommended) Hasura Admin Secret for privileged access, or properly configured default role permissions.

Setup and Installation

1. Clone the Repository (if applicable):

# git clone 
    # cd mcp-hasura-advanced

2. Install Dependencies:

pnpm install

3. Build the Server:

pnpm run build

This compiles the TypeScript code into the `dist` directory.

Running the Server

Execute the compiled script from your terminal, providing the Hasura endpoint URL and optionally the admin secret:

# Using pnpm start script (defined in package.json)
pnpm start  [ADMIN_SECRET]

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

Example:

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

or

node dist/index.js https://my-hasura.cloud/v1/graphql mysecretkey123

If no admin secret is needed (using default role permissions):

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

The server will start, attempt an initial schema introspection, connect to the STDIO transport, and log status messages to `stderr`. It listens for MCP JSON-RPC requests on `stdin` and sends responses to `stdout`.

Usage with MCP Clients (e.g., Cursor, Claude Desktop)

To connect this server to an MCP client like Cursor:

1. Find Absolute Paths:

2. Configure the Client: Open your client's configuration file (e.g., `settings.json` for Cursor, `claude_desktop_config.json` for Claude Desktop).

3. Add Server Entry: Add an entry under the appropriate key (e.g., `cursor.customMcpServers` array for Cursor, `mcpServers` object for Claude Desktop).

Example Cursor `settings.json`:

{
  // ... other settings ...
  "cursor.customMcpServers": [
    // ... other servers ...
    {
      "name": "My Advanced Hasura Server", // Name shown in Cursor UI
      "command": "/path/to/your/node", //  [SECRET]` to run the server directly with `ts-node` for faster iteration (no build step needed).
*   **Testing:** Test individual tools by running the server manually (`pnpm start ...`) and piping JSON-RPC requests to its `stdin`.