# jq-mcp

[![npm version](https://img.shields.io/npm/v/jq-mcp.svg)](https://www.npmjs.com/package/jq-mcp)
[![npm downloads](https://img.shields.io/npm/dm/jq-mcp.svg)](https://www.npmjs.com/package/jq-mcp)


An MCP server that exposes a single tool, `jq`, for running jq filters against JSON files on disk.

## Use

Add to your MCP client config:

```json
{
  "mcpServers": {
    "jq-mcp": {
      "command": "npx",
      "args": ["jq-mcp@latest"]
    }
  }
}
```

The `jq` tool takes `file` and `query` and returns the stdout of `jq <query> <file>`. By default it can read files under the server's working directory and `/tmp`.

## Advanced: custom allowlist

Set `ALLOWED_PATHS` (comma-separated directories) in the server's `env` to override the default `<cwd>,/tmp`:

```json
"env": { "ALLOWED_PATHS": "/path/to/allow,/another/path" }
```

Path matching normalizes the input before comparing, so:

- `..` segments cannot escape an allowed directory.
- Sibling directories that share a string prefix (e.g. `/foo/bar-evil` vs `/foo/bar`) are rejected — the check is path-boundary aware, not a naive `startsWith`.

## Develop

```sh
npm test     # node:test suite
npm run build
```