AI导哈

JSON查询处理服务

一个基于jq命令行工具的JSON数据查询和操作服务，提供JSON查询、数据格式化、复杂操作、文件处理和验证等功能。

  • by 247arjun
  • JavaScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 247arjun/mcp-jq

使用说明

JQ的MCP服务器

一个模型上下文协议（MCP）服务器，它为 jq 用于查询和操作JSON数据的命令行实用程序。

特性

  • JSON查询：使用jq语法查询JSON文件和数据
  • 数据格式：解析和格式化JSON数据
  • 复杂操作：支持复杂的jq过滤器和操作
  • 文件处理：大型JSON文件的流处理
  • 验证：JSON验证和密钥提取
  • 安全：通过输入验证安全执行子流程

先决条件

  • Node.js 18或更高版本
  • jq 系统上安装的命令行实用程序

安装jq

macOS：

brew install jq

Ubuntu/Debian：

sudo apt-get install jq

窗户： 下载自https://jqlang.github.io/jq/download/

安装

方法1：NPM安装（推荐）

# Install globally
npm install -g @247arjun/mcp-jq

# Or install locally in your project
npm install @247arjun/mcp-jq

方法2：来源

# Clone the repository
git clone https://github.com/247arjun/mcp-jq.git
cd mcp-jq

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Link globally
npm link

方法3：直接从GitHub

# Install directly from GitHub
npm install -g git+https://github.com/247arjun/mcp-jq.git

配置

Claude桌面设置

添加到您的Claude Desktop配置文件中：

地点：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "mcp-jq": {
      "command": "mcp-jq",
      "args": []
    }
  }
}

替代方案：使用npx（无需全局安装）

{
  "mcpServers": {
    "mcp-jq": {
      "command": "npx",
      "args": ["@247arjun/mcp-jq"]
    }
  }
}

地方发展设置

{
  "mcpServers": {
    "mcp-jq": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jq/build/index.js"]
    }
  }
}

添加配置后，重新启动Claude Desktop以加载MCP服务器。

可用工具

1. jq_query

使用jq语法查询JSON数据。

参数：

  • json_data （string）：要查询的JSON数据
  • filter （string）：jq过滤器表达式
  • raw_output （boolean，可选）：返回原始输出而不是JSON（默认值：false）

例子：

{
  "json_data": "{\"users\": [{\"name\": \"John\", \"age\": 30}]}",
  "filter": ".users[0].name"
}

2. jq_query_file

使用jq语法查询JSON文件。

参数：

  • file_path （string）：JSON文件的路径
  • filter （string）：jq过滤器表达式
  • raw_output （boolean，可选）：返回原始输出而不是JSON（默认值：false）

例子：

{
  "file_path": "./data/users.json",
  "filter": ".users | length"
}

3. jq_format

格式化和美化JSON数据。

参数：

  • json_data （string）：要格式化的JSON数据

例子：

{
  "json_data": "{\"name\":\"John\",\"age\":30}"
}

4. jq_validate

验证字符串是否为有效的JSON。

参数：

  • json_data （string）：要验证的JSON数据

例子：

{
  "json_data": "{\"name\": \"John\", \"age\": 30}"
}

5. jq_keys

从JSON对象或对象数组中获取所有键。

参数：

  • json_data （string）：从中提取密钥的JSON数据
  • recursive （boolean，可选）：递归获取密钥（默认值：false）

例子：

{
  "json_data": "{\"user\": {\"name\": \"John\", \"details\": {\"age\": 30}}}",
  "recursive": true
}

使用示例

从JSON查询用户名

{
  "tool": "jq_query",
  "json_data": "{\"users\": [{\"name\": \"John\"}, {\"name\": \"Jane\"}]}",
  "filter": ".users[].name"
}

格式化JSON数据

{
  "tool": "jq_format",
  "json_data": "{\"name\":\"John\",\"age\":30,\"city\":\"NYC\"}"
}

查询JSON文件

{
  "tool": "jq_query_file",
  "file_path": "./data/config.json",
  "filter": ".database.host"
}

发展

构建并运行

# Development with auto-rebuild
npm run dev

# Production build
npm run build

# Start the server
npm start

测试

# Run tests
npm test

项目结构

mcp-jq/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (after build)
├── examples/             # Sample JSON files for testing
│   ├── users.json
│   └── company.json
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── install.sh           # Installation script
├── test.js              # Test script
└── README.md            # This file

验证

测试服务器是否正常工作：

# Test the built server
node build/index.js

# Should show: "JQ MCP Server running on stdio"
# Press Ctrl+C to exit

故障排除

常见问题

  1. “找不到命令”错误

    • 确保全局安装mcp-jq： npm install -g @247arjun/mcp-jq
    • 或者使用npx： "command": "npx", "args": ["@247arjun/mcp-jq"]

  2. “权限被拒绝”错误

    • 检查文件权限： chmod +x build/index.js
    • 重建项目： npm run build

  3. MCP服务器未出现在Claude中

    • 验证配置文件中的JSON语法
    • 完全重新启动克劳德桌面
    • 检查命令路径是否正确

  4. “找不到jq命令”

    • 按照上述说明在您的系统上安装jq
    • 验证安装： jq --version

调试

通过设置环境变量启用详细日志记录：

# For development
DEBUG=1 node build/index.js

# Test with sample input
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js

安全说明

  • 使用spawn而不是shell安全执行子流程
  • 所有jq命令和文件路径的输入验证
  • 不执行任意shell命令
  • 文件操作的路径验证和清理
  • 使用Zod模式进行输入验证

相关 MCP