jq MCP Server

This project is an MCP (Model Context Protocol) server for AI models that allows executing jq expressions against JSON files.

What it does

The server exposes a tool that runs a jq filter on a JSON file and returns the result as text. It accepts the jq expression and the absolute path to the JSON file, and it handles execution errors.

Requirements

• Node.js
• npm, pnpm (recommended) or any compatible Node.js package manager

Installation

• Install the dependencies with:

npm install

• Or with pnpm:

pnpm install

For security reasons, the pnpm package manager is recommended. You can configure it with the following command before installing any dependencies:

pnpm config set minimum-release-age 1440 --global

This adds a layer of security against supply chain attacks.

If you use pnpm run pnpm approve-builds, select node-jq with <space> key and press <Enter>. Finally press y and press <Enter> to confirm.

• Or install dependencies with your favorite Node.js package manager.

Usage with MCP clients

This server is intended to be started by MCP-compatible clients; you do not need to run node main.js manually. Properly configured clients will start the server when needed. Below are example client configurations (replace /path/to/... with the correct path on your system).

• Continue (VSCode extension) — example config.yaml:

mcpServers:
    - name: jq MCP server
      command: npx
      args:
          - -y
          - node
          - /path/to/mcp_servers/jq/main.js
      env: {}

• Claude (desktop) — example claude_desktop_config.json:

{
    "mcpServers": {
        "jq": {
            "command": "npx",
            "args": ["-y", "node", "/path/to/mcp_servers/jq/main.js"]
        }
    }
}

• GitHub Copilot (VSCode). Press Ctrl+Shift+P (Windows or Linux) or Cmd+Shift+P (Mac) to open the Command Palette. Execute the MCP: Open User Configuration command. This creates a clean mcp.json in your global user profile directory. Edit the mcp.json file and place the following:

{
    "servers": {
        "jq": {
            "command": "npx",
            "args": ["-y", "node", "/path/to/mcp_servers/jq/main.js"]
        }
    }
}

• Generic MCP client (command line):

# A client can launch the server this way if it must be started manually
npx -y node /path/to/mcp_servers/jq/main.js

Tool exposed

The server exposes the following MCP tool:

• execute-jq-expression
  • Parameters:
    • filter: the jq expression to evaluate
    • filePath: the absolute path to the JSON file

Example

If the JSON file contains:

{
    "name": "Ada",
    "skills": ["jq", "JSON"]
}

You can use a filter such as:

.name

or:

.skills[]

Notes:

• Check the documentation of the MCP client you use for the exact configuration key names; the examples above are common templates.
• When chatting with the AI, make sure to provide the absolute path of JSON file and the jq expression.