JQ的MCP服务器
](https://badge.fury.io/js/@247arjun%2Fmcp-jq) ](https://www.npmjs.com/package/@247arjun/mcp-jq)
一个模型上下文协议（MCP）服务器，它为 jq 用于查询和操作JSON数据的命令行实用程序。
特性
- JSON查询：使用jq语法查询JSON文件和数据
- 数据格式：解析和格式化JSON数据
- 复杂操作：支持复杂的jq过滤器和操作
- 文件处理：大型JSON文件的流处理
- 验证：JSON验证和密钥提取
- 安全：通过输入验证安全执行子流程
先决条件
- Node.js 18或更高版本
jq系统上安装的命令行实用程序
安装jq
macOS：
brew install jqUbuntu/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故障排除
常见问题
- “找不到命令”错误
- 确保全局安装mcp-jq： npm install -g @247arjun/mcp-jq - 或者使用npx： "command": "npx", "args": ["@247arjun/mcp-jq"]
- “权限被拒绝”错误
- 检查文件权限： chmod +x build/index.js - 重建项目： npm run build
- MCP服务器未出现在Claude中
- 验证配置文件中的JSON语法 - 完全重新启动克劳德桌面 - 检查命令路径是否正确
- “找不到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模式进行输入验证