query-graphql
Execute GraphQL queries with custom variables and headers to interact with GraphQL endpoints and retrieve structured data from APIs.
Instructions
Query a GraphQL endpoint with the given query and variables. Optionally pass headers (e.g., for Authorization).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| headers | No | Optional JSON string of headers to include, e.g., {"Authorization": "Bearer ..."} | |
| query | Yes | ||
| variables | No |
Implementation Reference
- src/index.ts:135-244 (handler)The handler function that executes the GraphQL query, parses it, checks for mutations, sends the request to the endpoint, and returns the formatted response or error.const queryGraphqlHandler = async ({ query, variables, headers }: any) => { try { const parsedQuery = parse(query); const isMutation = parsedQuery.definitions.some( (def: any) => def.kind === "OperationDefinition" && def.operation === "mutation", ); if (isMutation && !env.ALLOW_MUTATIONS) { return { isError: true, content: [ { type: "text", text: "Mutations are not allowed unless you enable them in the configuration. Please use a query operation instead.", }, ], }; } } catch (error) { return { isError: true, content: [ { type: "text", text: `Invalid GraphQL query: ${error}`, }, ], }; } try { const toolHeaders = headers ? JSON.parse(headers) : {}; const allHeaders = { "Content-Type": "application/json", ...env.HEADERS, ...toolHeaders, }; let parsedVariables = null; if (variables) { if (typeof variables === 'string') { parsedVariables = JSON.parse(variables); } else { parsedVariables = variables; } } const response = await fetch(env.ENDPOINT, { method: "POST", headers: allHeaders, body: JSON.stringify({ query, variables: parsedVariables, }), }); if (!response.ok) { const responseText = await response.text(); return { isError: true, content: [ { type: "text", text: `GraphQL request failed: ${response.statusText}\n${responseText}`, }, ], }; } const rawData = await response.json(); const data = rawData; if (data.errors && data.errors.length > 0) { return { isError: true, content: [ { type: "text", text: `GraphQL errors: ${JSON.stringify(data.errors, null, 2)}`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], }; } catch (error) { return { isError: true, content: [ { type: "text", text: `Failed to execute GraphQL query: ${error}`, }, ], }; } };
- src/index.ts:250-257 (schema)Zod schema defining the input parameters: query (required string), variables (optional string), headers (optional JSON string for custom headers).{ query: z.string(), variables: z.string().optional(), headers: z .string() .optional() .describe("Optional JSON string of headers to include, e.g., {\"Authorization\": \"Bearer ...\"}"), },
- src/index.ts:247-259 (registration)MCP server.tool registration for the 'query-graphql' tool, including name, description, input schema, and handler reference.server.tool( "query-graphql", "Query a GraphQL endpoint with the given query and variables. Optionally pass headers (e.g., for Authorization).", { query: z.string(), variables: z.string().optional(), headers: z .string() .optional() .describe("Optional JSON string of headers to include, e.g., {\"Authorization\": \"Bearer ...\"}"), }, queryGraphqlHandler );
- src/index.ts:245-245 (registration)Maps the 'query-graphql' tool name to its handler in the toolHandlers Map, used for HTTP request handling.toolHandlers.set("query-graphql", queryGraphqlHandler);