@quicknode/mcp 0.0.1

package/README.md

@@ -0,0 +1,114 @@
+# ![QuickNode Logo](https://www.quicknode.com/compiled-assets/qn-logo-q.svg)uickNode MCP Server
+
+> **🚀 The official Model Context Protocol (MCP) server for QuickNode**
+>
+> Unleash the power of blockchain infrastructure from your AI workflows
+
+---
+
+## 🌟 What is QuickNode MCP?
+
+QuickNode MCP Server brings the power of QuickNode's blockchain infrastructure directly to your AI assistant. With this MCP server, you can:
+
+- **🔧 Set up and configure** QuickNode endpoints and infra across multiple networks
+- **📊 Monitor endpoint usage** and billing information
+- **⚡ Manage your QuickNode infrastructure** through natural language
+- **🛠️ Unlock blockchain operations** by provisioning the infrastructure you need
+
+Built by the team at [QuickNode](http://quicknode.com/), we're trailblazers in blockchain and web3 technology, tirelessly working to simplify blockchain infrastructure. Our combined passion, ingenuity, and dedication pave the way for seamless, high-performance API access across multiple platforms, shaping the future of digital interactions.
+
+---
+
+## 🚀 Getting Started
+
+Add to your config on your `claude_desktop_config.json`, Cursor's `mcp.json` or alike
+
+```json
+{
+  "mcpServers": {
+    "quicknode-mcp": {
+      "command": "npx",
+      "args": ["-y", "@quicknode/mcp"],
+      "env": {
+        "QUICKNODE_API_KEY": "<replace-with-qn-token>"
+      }
+    }
+  }
+}
+```
+
+Replace `<qn-token>` with a QuickNode API token. Can be created on the [QuickNode dashboard](https://dashboard.quicknode.com/api-keys)
+
+---
+
+## 📋 Notes
+
+This MCP server requires **Node.js 18.18.0 or higher**.
+
+### Installing Node.js
+
+If you don't have Node.js installed or need to upgrade:
+
+**Download from nodejs.org**
+
+- Visit [nodejs.org](https://nodejs.org/)
+- Download and install the LTS version (recommended)
+
+**Verify your installation:**
+
+```bash
+node --version  # Should show v18.18.0 or higher
+npm --version   # Should show npm version
+```
+
+---
+
+## 🛠️ Development Guide
+
+### How to run locally
+
+To run from local repo, put this server config on your `claude_desktop_config.json`, Cursor's `mcp.json` or alike
+
+```json
+{
+  "mcpServers": {
+    "quicknode-mcp": {
+      "command": "<absolute-path-to-repo>/qn-mcp/dist/index.js",
+      "env": {
+        "QUICKNODE_API_KEY": "<replace-with-qn-token>"
+      }
+    }
+  }
+}
+```
+
+To install dependencies
+
+```bash
+pnpm i
+```
+
+and kickstart the build with
+
+```bash
+pnpm build
+```
+
+can also run with watch mode
+
+```bash
+pnpm watch
+```
+
+Then restart Claude/reload Cursor config or similar, you should see resources/tools get picked up by the chat client.
+
+---
+
+## 💬 Feedback & Support
+
+We'd love to hear from you! If you have questions, suggestions, or run into any issues:
+
+- 📧 **Email us:** [devex@quicknode.com](mailto:devex@quicknode.com)
+- 🆘 **General support:** [QuickNode Support](https://support.quicknode.com/)
+
+Your feedback helps us make QuickNode even better! 🚀

package/dist/clients/base_http_client/base_client.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+class Client {
+    baseUrl;
+    token;
+    defaultHeaders;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.endsWith("/")
+            ? options.baseUrl.slice(0, -1)
+            : options.baseUrl;
+        this.token = options.token;
+        this.defaultHeaders = {
+            "Content-Type": "application/json",
+            "x-api-key": this.token,
+            ...options.headers,
+        };
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(path.startsWith("/") ? path.slice(1) : path, this.baseUrl);
+        // Add query parameters
+        if (options.params) {
+            Object.entries(options.params).forEach(([key, value]) => {
+                if (typeof value === "string") {
+                    url.searchParams.append(key, value);
+                }
+                else if (value !== undefined) {
+                    url.searchParams.append(key, value.toString());
+                }
+            });
+        }
+        const headers = {
+            ...this.defaultHeaders,
+            ...options.headers,
+        };
+        const requestOptions = {
+            method,
+            headers,
+        };
+        if (options.body && method !== "GET" && method !== "HEAD") {
+            requestOptions.body = JSON.stringify(options.body);
+        }
+        const response = await fetch(url.toString(), requestOptions);
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        // Return empty object for 204 No Content responses
+        if (response.status === 204) {
+            return {};
+        }
+        try {
+            return (await response.json());
+        }
+        catch (error) {
+            throw new Error(`Failed to parse response: ${error}`);
+        }
+    }
+    async get(path, options = {}) {
+        return this.request("GET", path, options);
+    }
+    async post(path, body, options = {}) {
+        return this.request("POST", path, { ...options, body });
+    }
+    async put(path, body, options = {}) {
+        return this.request("PUT", path, { ...options, body });
+    }
+    async patch(path, body, options = {}) {
+        return this.request("PATCH", path, { ...options, body });
+    }
+    async delete(path, options = {}) {
+        return this.request("DELETE", path, options);
+    }
+}
+exports.Client = Client;

package/dist/clients/base_http_client/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base_client"), exports);

package/dist/clients/console_api_client/console_client.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuickNodeClient = void 0;
+const base_client_1 = require("../base_http_client/base_client");
+class QuickNodeClient extends base_client_1.Client {
+    constructor(options) {
+        super({
+            ...options,
+            headers: {
+                ...options.headers,
+                "x-qn-sdk": "qn-mcp",
+            },
+        });
+    }
+    async listEndpoints(limit = 10, offset = 0) {
+        const { data } = await this.get("/v0/endpoints", {
+            params: {
+                limit: limit.toString(),
+                offset: offset.toString(),
+            },
+        });
+        return data.map((endpoint) => ({
+            ...endpoint,
+            name: endpointNameFromUrl(endpoint.http_url),
+        }));
+    }
+    async getEndpoint(id) {
+        return this.get(`/v0/endpoints/${id}`);
+    }
+    async createEndpoint(body) {
+        return this.post("/v0/endpoints", body);
+    }
+    async deleteEndpoint(id) {
+        return this.delete(`/v0/endpoints/${id}`);
+    }
+    async getChains() {
+        return this.get("/v0/chains");
+    }
+    async getRpcUsage(queryParams) {
+        return this.get("/v0/usage/rpc", {
+            params: queryParams,
+        });
+    }
+    async getRpcUsageByEndpoint(queryParams) {
+        return this.get("/v0/usage/rpc/by-endpoint", {
+            params: queryParams,
+        });
+    }
+    async getRpcUsageByMethod(queryParams) {
+        return this.get("/v0/usage/rpc/by-method", {
+            params: queryParams,
+        });
+    }
+    async getRpcUsageByChain(queryParams) {
+        return this.get("/v0/usage/rpc/by-chain", {
+            params: queryParams,
+        });
+    }
+    async getRpcEndpointSecurityOptions(endpointId) {
+        return this.get(`v0/endpoints/${endpointId}/security_options`);
+    }
+    async getEndpointLogs(queryParams) {
+        return this.get(`/v0/endpoints/${queryParams.endpoint_id}/logs`, {
+            params: queryParams,
+        });
+    }
+    async getEndpointLogDetails(queryParams) {
+        return this.get(`/v0/endpoints/${queryParams.endpoint_id}/log_details`, {
+            params: queryParams,
+        });
+    }
+    async getBillingInvoices() {
+        return this.get("/v0/billing/invoices");
+    }
+    async getBillingPayments() {
+        return this.get("/v0/billing/payments");
+    }
+    async getEndpointMetrics(endpointId, queryParams) {
+        return this.get(`/v0/endpoints/${endpointId}/metrics`, {
+            params: queryParams,
+        });
+    }
+    async updateRateLimits(endpointId, body) {
+        return this.put(`/v0/endpoints/${endpointId}/rate-limits`, body);
+    }
+    async getMethodRateLimits(endpointId) {
+        return this.get(`/v0/endpoints/${endpointId}/method-rate-limits`);
+    }
+    async createMethodRateLimit(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/method-rate-limits`, body);
+    }
+    async updateMethodRateLimit(endpointId, methodRateLimitId, body) {
+        return this.patch(`/v0/endpoints/${endpointId}/method-rate-limits/${methodRateLimitId}`, body);
+    }
+    async deleteMethodRateLimit(endpointId, methodRateLimitId) {
+        return this.delete(`/v0/endpoints/${endpointId}/method-rate-limits/${methodRateLimitId}`);
+    }
+    async getSecurityOptions(endpointId) {
+        return this.get(`/v0/endpoints/${endpointId}/security_options`);
+    }
+    async updateSecurityOptions(endpointId, body) {
+        return this.patch(`/v0/endpoints/${endpointId}/security_options`, body);
+    }
+    async createEndpointSecurityDomainMask(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/security/domain_masks`, body);
+    }
+    async deleteEndpointSecurityDomainMask(endpointId, domainMaskId) {
+        return this.delete(`/v0/endpoints/${endpointId}/security/domain_masks/${domainMaskId}`);
+    }
+    async createEndpointSecurityIp(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/security/ips`, body);
+    }
+    async deleteEndpointSecurityIp(endpointId, ipId) {
+        return this.delete(`/v0/endpoints/${endpointId}/security/ips/${ipId}`);
+    }
+    async createEndpointSecurityJwt(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/security/jwts`, body);
+    }
+    async deleteEndpointSecurityJwt(endpointId, jwtId) {
+        return this.delete(`/v0/endpoints/${endpointId}/security/jwts/${jwtId}`);
+    }
+    async createEndpointSecurityReferrer(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/security/referrers`, body);
+    }
+    async deleteEndpointSecurityReferrer(endpointId, referrerId) {
+        return this.delete(`/v0/endpoints/${endpointId}/security/referrers/${referrerId}`);
+    }
+    async createEndpointSecurityToken(endpointId, body) {
+        return this.post(`/v0/endpoints/${endpointId}/security/tokens`, body);
+    }
+    async deleteEndpointSecurityToken(endpointId, tokenId) {
+        return this.delete(`/v0/endpoints/${endpointId}/security/tokens/${tokenId}`);
+    }
+}
+exports.QuickNodeClient = QuickNodeClient;
+const endpointNameFromUrl = (url) => {
+    const match = url.match(/https:\/\/(.*)\.quiknode\.pro\//);
+    if (!match) {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    return match[1];
+};

package/dist/clients/console_api_client/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./console_client"), exports);
+__exportStar(require("./types"), exports);

package/dist/clients/console_api_client/types.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitStatus = exports.RateLimitInterval = exports.MetricsType = exports.MetricsPeriod = void 0;
+var MetricsPeriod;
+(function (MetricsPeriod) {
+    MetricsPeriod["HOUR"] = "hour";
+    MetricsPeriod["DAY"] = "day";
+    MetricsPeriod["WEEK"] = "week";
+    MetricsPeriod["MONTH"] = "month";
+})(MetricsPeriod || (exports.MetricsPeriod = MetricsPeriod = {}));
+var MetricsType;
+(function (MetricsType) {
+    MetricsType["METHOD_CALLS_OVER_TIME"] = "method_calls_over_time";
+    MetricsType["RESPONSE_STATUS_OVER_TIME"] = "response_status_over_time";
+    MetricsType["METHOD_CALL_BREAKDOWN"] = "method_call_breakdown";
+    MetricsType["RESPONSE_STATUS_BREAKDOWN"] = "response_status_breakdown";
+    MetricsType["METHOD_RESPONSE_TIME_MAX"] = "method_response_time_max";
+})(MetricsType || (exports.MetricsType = MetricsType = {}));
+var RateLimitInterval;
+(function (RateLimitInterval) {
+    RateLimitInterval["SECOND"] = "second";
+    RateLimitInterval["MINUTE"] = "minute";
+    RateLimitInterval["HOUR"] = "hour";
+})(RateLimitInterval || (exports.RateLimitInterval = RateLimitInterval = {}));
+var RateLimitStatus;
+(function (RateLimitStatus) {
+    RateLimitStatus["ENABLED"] = "enabled";
+    RateLimitStatus["DISABLED"] = "disabled";
+})(RateLimitStatus || (exports.RateLimitStatus = RateLimitStatus = {}));

package/dist/common/generic_args.js

@@ -0,0 +1,29 @@
+"use strict";
+// Define generic args for the tools and resources to have unified descriptions
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genericArgs = exports.endpointIdArgs = exports.timeRangeArgs = void 0;
+const zod_1 = require("zod");
+const utils_1 = require("./utils");
+exports.timeRangeArgs = {
+    start_time: zod_1.z
+        .string()
+        .describe("The start time of the time range (ISO 8601 format)")
+        .refine(utils_1.isValidIsoString, {
+        message: "start_time must be a valid ISO 8601 date string",
+    }),
+    end_time: zod_1.z
+        .string()
+        .describe("The end time of the time range (ISO 8601 format)")
+        .refine(utils_1.isValidIsoString, {
+        message: "end_time must be a valid ISO 8601 date string",
+    }),
+};
+exports.endpointIdArgs = {
+    endpoint_id: zod_1.z
+        .string()
+        .describe("The unique identifier of the QuickNode endpoint"),
+};
+exports.genericArgs = {
+    timeRangeArgs: exports.timeRangeArgs,
+    endpointIdArgs: exports.endpointIdArgs,
+};

package/dist/common/utils.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isoToUnixTimestamp = isoToUnixTimestamp;
+exports.unixTimestampToIso = unixTimestampToIso;
+exports.isValidIsoString = isValidIsoString;
+exports.getCurrentUnixTimestamp = getCurrentUnixTimestamp;
+/**
+ * Converts an ISO date string to a UNIX timestamp (seconds since epoch)
+ * @param isoString - The ISO date string to convert
+ * @returns The UNIX timestamp in seconds, or null if the input is invalid
+ */
+function isoToUnixTimestamp(isoString) {
+    try {
+        const date = new Date(isoString);
+        // Check if the date is valid
+        if (isNaN(date.getTime())) {
+            return null;
+        }
+        // Convert to UNIX timestamp (seconds since epoch)
+        return Math.floor(date.getTime() / 1000);
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Converts a UNIX timestamp (seconds since epoch) to an ISO date string
+ * @param unixTimestamp - The UNIX timestamp in seconds
+ * @returns The ISO date string, or null if the input is invalid
+ */
+function unixTimestampToIso(unixTimestamp) {
+    try {
+        // Check if the timestamp is valid (positive number)
+        if (unixTimestamp < 0 || !Number.isFinite(unixTimestamp)) {
+            return null;
+        }
+        // Convert to milliseconds and create Date object
+        const date = new Date(unixTimestamp * 1000);
+        // Return ISO string
+        return date.toISOString();
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Validates if a string is a valid ISO date string
+ * @param isoString - The string to validate
+ * @returns True if the string is a valid ISO date string, false otherwise
+ */
+function isValidIsoString(isoString) {
+    try {
+        const date = new Date(isoString);
+        return !isNaN(date.getTime());
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Gets the current UNIX timestamp in seconds
+ * @returns The current UNIX timestamp
+ */
+function getCurrentUnixTimestamp() {
+    return Math.floor(Date.now() / 1000);
+}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const console_api_client_1 = require("./clients/console_api_client");
+const resource_1 = require("./resource");
+const tools_1 = require("./tools");
+const QUICKNODE_API_KEY = process.env.QUICKNODE_API_KEY;
+const QUICKNODE_API_URL = process.env.QUICKNODE_API_URL || "https://api.quicknode.com";
+if (!QUICKNODE_API_KEY) {
+    console.error("QUICKNODE_API_KEY must be set");
+    process.exit(1);
+}
+const client = new console_api_client_1.QuickNodeClient({
+    token: QUICKNODE_API_KEY,
+    baseUrl: QUICKNODE_API_URL,
+});
+const server = new mcp_js_1.McpServer({
+    name: "QuickNode Web3 InfrastructureMCP Server",
+    description: "A MCP server for interacting with QuickNode, leading Web3 infrastructure provider, this server can be used to manage web3 infrastructure (i.e. rpc endpoints) under a user's QuickNode account",
+    version: "0.0.1",
+});
+(0, tools_1.setTools)(server, client);
+(0, resource_1.setResources)(server, client);
+async function runServer() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Secure MCP Filesystem Server running on stdio");
+}
+runServer().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/dist/resource/endpoints.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setEndpointResources = setEndpointResources;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+function setEndpointResources(server, client) {
+    server.resource("endpoint", new mcp_js_1.ResourceTemplate("endpoint://{name}", {
+        list: async (data) => {
+            const endpoints = await client.listEndpoints();
+            return {
+                resources: endpoints.map((endpoint) => ({
+                    name: endpoint.name,
+                    uri: `endpoint://${endpoint.name}`,
+                })),
+            };
+        },
+        complete: {
+            name: async (data) => {
+                const endpoints = await client.listEndpoints();
+                return endpoints
+                    .map((endpoint) => endpoint.name)
+                    .filter((name) => name.startsWith(data));
+            },
+        },
+    }), {
+        description: "A resource for listing and getting QuickNode endpoints information",
+    }, async (uri, { name }) => {
+        if (Array.isArray(name)) {
+            console.error("\n\n---name is array this is not supported yet\n", {
+                name,
+            });
+        }
+        const endpoints = await client.listEndpoints();
+        const endpoint = endpoints.find((endpoint) => endpoint.name === name);
+        if (!endpoint) {
+            throw new Error(`Endpoint not found: ${name}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(endpoint, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/resource/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setResources = setResources;
+const endpoints_1 = require("./endpoints");
+function setResources(server, client) {
+    (0, endpoints_1.setEndpointResources)(server, client);
+}

package/dist/tools/billing.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setBillingTools = setBillingTools;
+const utils_1 = require("../common/utils");
+function setBillingTools(server, client) {
+    server.registerTool("get-billing-invoices", {
+        description: "Get all billing invoices for the user's QuickNode account",
+    }, async () => {
+        const invoices = await client.getBillingInvoices();
+        const data = {
+            invoices: invoices.data.invoices.map((invoice) => ({
+                ...invoice,
+                period_end: (0, utils_1.unixTimestampToIso)(invoice.period_end),
+                period_start: (0, utils_1.unixTimestampToIso)(invoice.period_start),
+                created: (0, utils_1.unixTimestampToIso)(invoice.created),
+            })),
+        };
+        return {
+            structuredContent: { data },
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("get-billing-payments", {
+        description: "Get all billing payments for the user's QuickNode account",
+    }, async () => {
+        const payments = await client.getBillingPayments();
+        const data = {
+            payments: payments.data.payments.map((payment) => ({
+                ...payment,
+                created_at: (0, utils_1.unixTimestampToIso)(parseInt(payment.created_at)),
+            })),
+        };
+        return {
+            structuredContent: { data },
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(data, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/chains.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setChainTools = setChainTools;
+function setChainTools(server, client) {
+    server.registerTool("get-chains", {
+        description: "Get all chains supported by QuickNode",
+    }, async () => {
+        const chains = await client.getChains();
+        return {
+            structuredContent: { data: chains.data },
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(chains.data, null, 2),
+                },
+            ],
+        };
+    });
+}