使用说明

JSON MCP服务器

一个模型上下文协议（MCP）服务器，提供强大的JSON操作工具，使用 node-jq 本地安装 jq 二进制、原生Node.js fs操作，以及 genson-js.

先决条件

🚨 必需：在您的系统上安装jq二进制文件

窗户：

# Chocolatey (recommended)
choco install jq

# Scoop
scoop install jq

# Manual download
# Download jq.exe from https://stedolan.github.io/jq/download/
# Place in PATH or use --jq-path parameter

# WSL (if using Windows Subsystem for Linux)
wsl -e sudo apt-get install jq

macOS：

brew install jq

Linux：

# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL/Fedora
sudo yum install jq  # or sudo dnf install jq

# Arch Linux
sudo pacman -S jq

验证安装：

# Windows (Command Prompt or PowerShell)
jq --version

# Unix/Linux/macOS
jq --version
# Should output something like: jq-1.6

特性

查询JSON：使用jq符号查询具有复杂过滤器和转换的JSON文件
生成JSON模式：从现有JSON数据自动生成JSON模式
验证JSON架构：确保JSON模式格式正确且有效
S3同步：启动时使用智能缓存自动同步AWS S3中的JSON文件

安装

mkdir json-mcp-server
cd json-mcp-server

保存提供的文件(index.js, package.json)在此目录中
清理安装依赖关系：

# Clean any existing installations first
npm run clean  # or manually: rm -rf node_modules package-lock.json
npm install

使脚本可执行（Unix/Linux/macOS）：

chmod +x index.js

Claude桌面安装

基本配置

Mac/Linux:

{
  "mcpServers": {
    "json-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/index.js",
        "--verbose=true",
        "--file-path=/path/to/file.json",
        "--jq-path=/path/to/jq"
      ]
    }
  }
}

视窗:

{
  "mcpServers": {
    "json-mcp-server": {
      "command": "node",
      "args": [
        "C:\\path\\to\\index.js",
        "--verbose=true",
        "--file-path=C:\\path\\to\\file.json",
        "--jq-path=C:\\path\\to\\jq.exe"
      ]
    }
  }
}

S3同步配置（可选）

要启用自动S3同步，请添加AWS凭据和S3参数。备注：S3同步仅在两者都运行时运行 --s3-uri 和 --file-path 提供了参数：

{
  "mcpServers": {
    "json-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/index.js",
        "--verbose=true",
        "--file-path=/absolute/path/to/local-data.json",
        "--s3-uri=s3://your-bucket-name/path/to/data.json",
        "--aws-region=us-east-1"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

用法

命令行参数

--verbose=true：启用详细日志记录（默认值：false）
--file-path=/path/to/file.json：为操作设置默认文件路径（可选）
--jq-path=/path/to/jq：指定自定义jq二进制路径（如果未提供，则自动检测）
--s3-uri=s3://bucket/key：启动时要同步的S3 URI（可选）
--aws-region=region：用于S3操作的AWS区域（默认：us-east-1）

启动服务器

Windows（命令提示符）：

REM Basic usage (auto-detects jq)
node index.js

REM With verbose logging
node index.js --verbose=true

REM With default file path (use forward slashes or escape backslashes)
node index.js --verbose=true --file-path=C:/Users/username/data.json

REM With custom jq binary path
node index.js --verbose=true --jq-path="C:\Program Files\jq\jq.exe"

Windows（PowerShell）：

# Basic usage
node index.js

# With verbose logging
node index.js --verbose=true

# With default file path
node index.js --verbose=true --file-path="C:\Users\username\data.json"

# With custom jq binary path
node index.js --verbose=true --jq-path="C:\Program Files\jq\jq.exe"

Unix/Linux/macOS：

# Basic usage (auto-detects jq)
node index.js

# With verbose logging
node index.js --verbose=true

# With default file path
node index.js --verbose=true --file-path=/home/user/data.json

# With custom jq binary path
node index.js --verbose=true --jq-path=/usr/local/bin/jq

# With S3 sync (requires AWS credentials in environment)
node index.js --verbose=true --file-path=/home/user/data.json --s3-uri=s3://my-bucket/data.json --aws-region=us-west-2

使用npm脚本（所有平台）：

npm start
npm run dev  # with verbose logging

工具

1.查询_json

使用jq符号查询JSON数据。

参数：

filePath （字符串，如果设置了默认值，则可选）：JSON文件的绝对路径
query （字符串，必填）：jq查询表达式

示例查询：

"." -返回整个JSON
".users" -获取用户数组
".users[0].name" -获取第一个用户名
".users[] | select(.active == true)" -筛选活跃用户
".[].price | add" -将所有价格相加

2.generate_json_schema

使用genson-js从JSON文件生成JSON模式。

参数：

filePath （字符串，如果设置了默认值，则可选）：JSON文件的绝对路径

输出： 描述数据结构的完整JSON模式。

3.validate_json_schema

验证JSON模式的格式是否正确。

参数：

schema （object）：要验证的JSON模式对象，OR
schemaFilePath （string）：包含JSON模式的文件的路径

输出： 带有详细反馈的验证结果。

JSON数据示例

创建测试文件 test-data.json:

{
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "active": true,
      "roles": ["user", "admin"]
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "active": false,
      "roles": ["user"]
    }
  ],
  "metadata": {
    "version": "1.0",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

MCP客户端使用示例

连接到MCP客户端后，您可以使用以下工具：

查询示例

// Get all active users
query_json({
  filePath: "/absolute/path/to/test-data.json",
  query: ".users[] | select(.active == true)"
})

// Get user emails
query_json({
  filePath: "/absolute/path/to/test-data.json",
  query: ".users[].email"
})

// Count total users
query_json({
  filePath: "/absolute/path/to/test-data.json",
  query: ".users | length"
})

模式生成

generate_json_schema({
  filePath: "/absolute/path/to/test-data.json"
})

架构验证

validate_json_schema({
  schema: {
    "type": "object",
    "properties": {
      "name": {"type": "string"}
    },
    "required": ["name"]
  }
})

错误处理

服务器为以下对象提供详细的错误消息：

文件路径无效
jq查询格式错误
JSON数据无效
架构验证错误
文件访问问题

需求

Node.js>=18.0.0
访问文件系统以读取JSON文件
为了安全起见，文件必须使用绝对路径

S3同步功能（可选）

当以下情况发生时，服务器可以在启动时自动同步AWS S3中的JSON文件 --s3-uri 提供了论据。此功能：

智能同步：仅当S3文件比本地文件新或本地文件不存在时下载
启动集成：同步发生在服务器连接之前，确保数据新鲜
错误恢复：即使S3同步失败，服务器也会继续启动
进度报告：以详细模式显示下载进度

AWS凭据配置

服务器支持多种AWS凭据方法：

环境变量 （建议用于Claude Desktop）：

AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=us-east-1

AWS简介：使用默认的AWS配置文件或AWS CLI配置
IAM角色：适用于EC2实例或容器化环境
AWS SSO：单点登录凭据

S3使用示例

# Basic S3 sync
node index.js --s3-uri="s3://my-bucket/data.json" --file-path="/absolute/path/to/data.json"

# With verbose logging
node index.js --s3-uri="s3://my-bucket/data.json" --file-path="/path/to/data.json" --verbose=true

# Custom AWS region
node index.js --s3-uri="s3://my-bucket/data.json" --file-path="/path/to/data.json" --aws-region="eu-west-1"

依赖项

@modelcontextprotocol/sdk：MCP协议实现（最新v1.x）
node-jq：用于jq二进制文件的Node.js包装器（使用您的本地jq安装）
genson-js：JSON模式生成
ajv：JSON模式验证
commander：命令行参数解析
which：二进制路径检测实用程序
@aws-sdk/client-s3：用于文件同步的AWS S3客户端

故障排除

jq二进制问题

如果你收到“jq-binary not found”错误：

窗户：

安装jq：按照上面的先决条件部分进行操作

检查路径：确保jq在您的系统PATH中

where jq
REM Should show path like: C:\ProgramData\chocolatey\bin\jq.exe

尝试jq.exe：某些Windows安装使用 jq.exe
```
jq.exe --version
```
自定义路径：使用 --jq-path 如果jq位于非标准位置
```
node index.js --jq-path="C:\tools\jq\jq.exe"
```

Unix/Linux/macOS：

安装jq：按照上面的先决条件部分进行操作

检查路径：确保jq在您的系统PATH中

which jq  # Should show path like /usr/local/bin/jq

自定义路径：使用 --jq-path 如果jq位于非标准位置
```
node index.js --jq-path=/custom/path/to/jq
```

依赖性问题

如果您遇到依赖关系问题：

清洁安装:
```
npm run clean
npm install
```
节点版本：确保您使用的是Node.js>=18.0.0
```
node --version
```
清除npm缓存:
```
npm cache clean --force
```

S3同步问题

如果遇到S3同步错误：

检查AWS凭据：确保设置了AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY
验证存储桶名称：确保S3存储桶名称正确且可访问
检查权限：确保您的AWS凭据具有对S3存储桶的读取权限
验证区域：确保AWS区域与您的bucket区域匹配
检查文件路径：确保本地文件路径是绝对的，并且目录存在

S3常见错误：

NoSuchBucket：存储桶名称不正确或不存在
AccessDenied：您的AWS凭据缺乏访问存储桶的权限
NotFound：指定的S3密钥（文件路径）在bucket中不存在

权限问题

窗户：

通常不需要更改权限
如果遇到拒绝访问错误，请以管理员身份运行命令提示符或PowerShell
确保jq.exe未被防病毒软件阻止

Unix/Linux/macOS： 如果您遇到权限错误：

chmod +x index.js
# And ensure jq binary is executable
chmod +x $(which jq)

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

使用说明

JSON MCP服务器

先决条件

特性

安装

Claude桌面安装

基本配置

S3同步配置（可选）

用法

命令行参数

启动服务器

工具

1.查询_json

2.generate_json_schema

3.validate_json_schema

JSON数据示例

MCP客户端使用示例

查询示例

模式生成

架构验证

错误处理

需求

S3同步功能（可选）

AWS凭据配置

S3使用示例

依赖项

故障排除

jq二进制问题

依赖性问题

S3同步问题

权限问题

贡献

许可证

相关 MCP

MySQL查询服务器

MongoDB 数据库 MCP 服务器

n8n工作流管理服务

Wikidata API服务器

Ledger CLI MCP服务器

SQLite数据库管理工具