Enables execution of GraphQL queries and mutations against a Hasura endpoint, with support for introspection, type exploration, and schema analysis.
Provides tools for interacting with a Hasura GraphQL endpoint, enabling access to schema information, executing queries and mutations, managing tables, previewing data, and performing aggregations.
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 (
Provides the full GraphQL schema definition obtained via standard introspection.
MIME Type:
application/json
Agents can read this resource to understand the complete structure of the API, including types, fields, arguments, directives, etc.
Tools:
run_graphql_query
Description: Executes a read-only GraphQL query against the Hasura endpoint. Use this for fetching data when a specific tool isn't available. Ensure the query does not modify data. Example:
Input:
{ query: string, variables?: object }
Note: Performs a basic check to prevent execution of strings starting with
mutation
. Primarily relies on the query itself being read-only.
run_graphql_mutation
Description: Executes a GraphQL mutation to insert, update, or delete data. Use with caution, ensure the operation is intended and safe. Relies on Hasura permissions configured for the provided Admin Secret or default role. Example:
Input:
{ mutation: string, variables?: object }
Security: Allows any mutation permitted by the Hasura role. Ensure appropriate Hasura permissions are configured.
list_tables
Description: Lists available data tables (or collections) managed by Hasura, organized by schema with descriptions, based on introspection heuristics (looks for object types with an 'id' field, excluding internal/aggregate types). Useful for discovering available data sources.
Input:
{ schemaName?: string }
(Optional schema name, attempts to infer from field descriptions if possible, defaults to 'public' conceptually)
describe_table
Description: Shows the structure of a specific table including all its columns (fields) with their GraphQL types and descriptions.
Input:
{ tableName: string, schemaName?: string }
list_root_fields
Description: Lists the available top-level query, mutation, or subscription fields from the GraphQL schema. Useful for understanding the primary entry points for operations.
Input:
{ fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' }
(Optional filter)
describe_graphql_type
Description: Provides details about a specific GraphQL type (Object, Input, Scalar, Enum, Interface, Union) using schema introspection. Essential for understanding how to structure queries or mutations involving specific types.
Input:
{ typeName: string }
(Case-sensitive type name)
preview_table_data
Description: Fetches a limited sample of rows (default 5) from a specified table to preview its data structure and content. Selects common scalar and enum fields automatically.
Input:
{ tableName: string, limit?: number }
aggregate_data
Description: Performs a simple aggregation (count, sum, avg, min, max) on a specified table, optionally applying a Hasura 'where' filter. Use 'list_tables' to find table names. Requires 'field' for non-count aggregations.
Input:
{ tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }
health_check
Description: Checks if the configured Hasura GraphQL endpoint is reachable and responding to a basic GraphQL query (
{ __typename }
). Can optionally check a specific HTTP health endpoint URL if known.Input:
{ healthEndpointUrl?: string }
(Optional specific health URL)
Requirements
Node.js (v18 or higher recommended, check
.nvmrc
orpackage.json engines
if specified)pnpm
(ornpm
/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
Clone the Repository (if applicable):
# git clone <repository_url> # cd mcp-hasura-advancedInstall Dependencies:
pnpm installBuild the Server:
pnpm run buildThis 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:
Example:
or
If no admin secret is needed (using default role permissions):
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:
Find Absolute Paths:
Node executable: Run
which node
in your terminal.Server script: Navigate to the
mcp-hasura-advanced
directory and runpwd
. Append/dist/index.js
to the result.Project directory: The output of
pwd
.
Configure the Client: Open your client's configuration file (e.g.,
settings.json
for Cursor,claude_desktop_config.json
for Claude Desktop).Add Server Entry: Add an entry under the appropriate key (e.g.,
cursor.customMcpServers
array for Cursor,mcpServers
object for Claude Desktop).
Example Cursor
Example Claude Desktop
Replace Placeholders: Update all placeholders (
/path/to/...
,https://YOUR...
,YOUR_ADMIN_SECRET
) with your actual values.Restart/Reload Client: Save the configuration and restart or reload your MCP client application.
Select Server: Choose "My Advanced Hasura Server" (or the name you specified) in the client's UI.
Interact: Use natural language prompts in your client's chat to leverage the server's tools (e.g., "List tables using the Hasura server", "Describe the 'users' table", "Preview data from the 'orders' table", "Run the query
{ products { name price } }
using the Hasura server").
Development
Run in Dev Mode: Use
pnpm run dev <ENDPOINT> [SECRET]
to run the server directly withts-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 itsstdin
.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol server that enables AI agents to dynamically interact with Hasura GraphQL endpoints through natural language, supporting schema discovery, data querying/manipulation, and aggregations.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI agents to interact with local Logseq knowledge graphs, supporting operations like creating/editing pages and blocks, searching content, and managing journal entries.Last updated -1314MIT License
- -security-license-qualityA Model Context Protocol server that connects to Microsoft Graph API, allowing AI assistants to query and access data from Microsoft Entra ID (formerly Azure Active Directory).
CodeAlive MCPofficial
-securityAlicense-qualityA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.Last updated -55MIT License- -securityFlicense-qualityModel Context Protocol server that allows AI assistants to interact with Jira, supporting operations like creating tickets and fetching project information directly from the cursor.Last updated -1