jq MCP Server

A simple Model Context Protocol (MCP) server that provides jq command execution capabilities.

Overview

This server exposes the jq JSON processor as an MCP tool, allowing AI assistants and other MCP clients to execute jq expressions on JSON content. The server is built in Go and packaged as a minimal container image.

Important: This project has no association with the jq project. It is an independent MCP server implementation that uses jq as an external tool.

Features

• Execute jq expressions on JSON content
• Multi-architecture support (amd64, arm64)
• Minimal container image based on scratch
• Secure execution using Go's exec.CommandContext
• MCP protocol compliance

Available Tools

jq

Execute jq expressions on JSON data.

Parameters:

• expression (required): The jq expression to execute
• content (required): JSON content as a string

Example:

{
  "name": "jq",
  "arguments": {
    "expression": ".name",
    "content": "{\"name\": \"example\", \"value\": 42}"
  }
}

Usage

Container

Pull and run the pre-built container:

docker run -i ghcr.io/007/jq-mcp-server:latest

To process JSON files from the host system, read the file content and pass it via the content parameter.

Building from Source

1. Clone the repository

2. Build the container:

   ./build.sh
   

3. Run locally:

   go run main.go
   

Container Build

The project includes a multi-stage Dockerfile that:

• Downloads jq directly from GitHub releases
• Builds a statically linked Go binary
• Creates a minimal scratch-based image
• Supports both amd64 and arm64 architectures

Build script supports:

./build.sh [tag] [platforms]

Examples:

./build.sh latest                    # Build for both amd64 and arm64
./build.sh v1.0.0 linux/amd64       # Build only for amd64

MCP Integration

This server implements the MCP specification and can be used with any MCP-compatible client. The server communicates via JSON-RPC over stdin/stdout.

Security

• Runs as non-root user (UID 1000)
• Uses scratch base image for minimal attack surface
• Executes jq safely using Go's exec package
• No shell injection vulnerabilities

License

This project is independent of and not affiliated with the jq project.