Provides dual-mode JSON querying over JSON data with jq syntax via MCP, supporting stdio and HTTP transports, real-time updates, and secure access.
Configuration
View docs{
"mcpServers": {
"berrydev-ai-gojq-mcp": {
"url": "http://my-server.com:8080/mcp",
"headers": {
"EXAMPLE_ENV": "VALUE"
}
}
}
}You run a dual‑mode JSON query tool that acts as an MCP server and can also function as a standalone CLI. It lets you execute jq-style queries on JSON data, watch for changes, and connect securely over multiple transports. This guide shows how to use the server with an MCP client, how to install it, and practical patterns for querying single or multiple files.
Run the server locally to connect with MCP clients or use it directly in CLI mode for ad hoc data exploration. In MCP server mode you can start the process and connect via stdio from a client, or expose an HTTP transport for web integrations. The same tool supports real-time notifications when data files change and enforces validation of file existence, readability, and JSON correctness.
To use the server with an MCP client in stdio mode, start the server from its binary. A typical setup in a client configuration uses the stdio transport and points to your local gojq-mcp binary:
``
command: gojq-mcp
``
This enables tight, local integration where the client communicates over standard input/output channels.
To connect via HTTP transport from an MCP client, reference the HTTP endpoint when configuring the client. The example shows how you might configure a remote MCP URL that the client can reach over HTTP, ensuring the server URL is reachable and secured as needed. The transport supports bearer token authentication for secure communication.
Prerequisites: you need a working Go toolchain to build from source, and you may want a package manager or build tool for convenience.
# Prerequisites
- Go (1.19+)
- Git
# Option A: Build from source
git clone https://github.com/berrydev-ai/gojq-mcp.git
cd gojq-mcp
make build
# or
go build -o dist/gojq-mcp .
# Run the built binary
./dist/gojq-mcp -hConfiguration options let you tailor transports, prompts, and instructions used by MCP clients. You can run with a built‑in default setup or supply a YAML configuration to control how data is presented to clients and which files are watched for changes.
Multiple transports are supported: stdio for local MCP clients, HTTP streaming for web integrations, and SSE for server-sent events with authentication. You can adapt the configuration to your environment by providing a data path, defining prompts, and setting up instructions that guide client interactions.
The tool exposes a dedicated interface for the MCP tool set, including a run_jq tool that executes jq filters against one or more JSON files. It validates file existence, readability, and JSON syntax before processing, and it supports multi‑file queries by using the inputs function to access data from multiple sources.
Tool: run_jq Description: Query JSON files using jq filter syntax with support for single and multiple files. It validates file patterns, executes the filter, and returns results as JSON.
Query JSON files using jq filter syntax with support for single and multiple files. It validates file patterns, executes the filter, and returns results as JSON.