跳到主要内容

MCP注册表（2025-09-08）————server.json 格式规范

· 阅读需 11 分钟

翻译自：https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md

server.json 文件是一种标准化的方式，用于描述 MCP 服务器，以便进行注册表发布、客户端发现和包管理。

另请参阅：

  • 有关创建和使用 server.json 文件的逐步说明，请参阅发布指南。
  • 有关发布到官方注册表时验证要求的理解，请参阅官方注册表要求。

浏览完整架构​

📋 以交互方式查看完整规范: 在架构查看器中打开 server.schema.json，例如 json-schema.app。

该架构包含所有字段定义、验证规则、示例和详细描述。

官方注册表在此基础上还有一些额外的限制。详情请参见官方注册表要求。

例子​

基本服务器与NPM包​

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/brave-search",
  "description": "MCP server for Brave Search API integration",
  "status": "active",
  "website_url": "https://anonymous.modelcontextprotocol.io/examples",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "@modelcontextprotocol/server-brave-search",
      "version": "1.0.2",
      "transport": {
        "type": "stdio"
      },
      "environment_variables": [
        {
          "name": "BRAVE_API_KEY",
          "description": "Brave Search API Key",
          "is_required": true,
          "is_secret": true
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "npm-publisher",
      "version": "1.0.1",
      "build_info": {
        "timestamp": "2023-12-01T10:30:00Z"
      }
    }
  }
}

单体仓库中的带子文件夹的服务器​

对于位于大型代码库（单仓库结构）子目录中的MCP服务器，请使用 subfolder 字段来指定相对路径：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol/everything",
  "description": "MCP服务器，测试MCP协议的所有功能",
  "status": "active",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github",
    "subfolder": "src/everything"
  },
  "version": "0.6.2",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "@modelcontextprotocol/everything",
      "version": "0.6.2",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "npm-publisher",
      "version": "1.0.1",
      "build_info": {
        "timestamp": "2023-12-01T10:30:00Z"
      }
    }
  }
}

启动MCP服务器所需的常量（固定）参数​

假设你的MCP服务器应用程序需要mcp start命令行参数才能以MCP服务器模式启动。将其表示为类似这样的位置参数：

{
  "name": "io.github.joelverhagen/knapcode-samplemcpserver",
  "description": "随机数和随机天气的示例 NuGet MCP 服务器",
  "version": "0.4.0-beta",
  "packages": [
    {
      "registry_type": "nuget",
      "registry_base_url": "https://api.nuget.org",
      "identifier": "Knapcode.SampleMcpServer",
      "version": "0.4.0-beta",
      "transport": {
        "type": "stdio"
      },
      "package_arguments": [
        {
          "type": "positional",
          "value": "mcp"
        },
        {
          "type": "positional",
          "value": "start"
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "nuget-publisher",
      "version": "2.1.0",
      "build_info": {
        "timestamp": "2023-11-15T14:22:00Z",
        "pipeline_id": "nuget-build-456"
      }
    }
  }
}

这实际上会指示MCP客户端执行 dnx Knapcode.SampleMcpServer@0.4.0-beta -- mcp start，而不是默认的 dnx Knapcode.SampleMcpServer@0.4.0-beta（当未提供 package_arguments 时）。

具有多个软件包的文件系统服务器​

json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.modelcontextprotocol/filesystem",
  "description": "实现文件系统操作的Model Context Protocol (MCP)的Node.js服务器。",
  "status": "active",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github",
    "id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "@modelcontextprotocol/server-filesystem",
      "version": "1.0.2",
      "transport": {
        "type": "stdio"
      },
      "package_arguments": [
        {
          "type": "位置参数",
          "value_hint": "目标目录",
          "description": "访问路径",
          "default": "/Users/username/Desktop",
          "is_required": true,
          "is_repeated": true
        }
      ],
      "environment_variables": [
        {
          "name": "LOG_LEVEL",
          "description": "日志级别（debug, info, warn, error）",
          "default": "info"
        }
      ]
    },
    {
      "registry_type": "oci",
      "registry_base_url": "https://docker.io",
      "identifier": "mcp/filesystem",
      "version": "1.0.2",
      "transport": {
        "type": "stdio"
      },
      "runtime_arguments": [
        {
          "type": "命名",
          "description": "将一个卷挂载到容器中",
          "name": "--mount",
          "value": "type=bind,src={source_path},dst={target_path}",
          "is_required": true,
          "is_repeated": true,
          "variables": {
            "source_path": {
              "description": "主机上的源路径",
              "format": "文件路径",
              "is_required": true
            },
            "target_path": {
              "description": "挂载到容器内的路径。路径应根植于`/project`目录。",
              "is_required": true,
              "default": "/project"
            }
          }
        }
      ],
      "package_arguments": [
        {
          "type": "位置参数",
          "value_hint": "目标目录",
          "value": "/project"
        }
      ],
      "environment_variables": [
        {
          "name": "LOG_LEVEL",
          "description": "日志级别（debug, info, warn, error）",
          "default": "info"
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "ci-publisher",
      "version": "3.2.1",
      "build_info": {
        "commit": "a1b2c3d4e5f6789",
        "timestamp": "2023-12-01T10:30:00Z",
        "pipeline_id": "filesystem-build-789",
        "environment": "production"
      }
    }
  }
}

远程服务器示例​

{
  "name": "io.modelcontextprotocol.anonymous/mcp-fs",
  "description": "云托管的MCP文件系统服务器",
  "repository": {
    "url": "https://github.com/example/remote-fs",
    "source": "github",
    "id": "xyz789ab-cdef-0123-4567-890ghijklmno"
  },
  "version": "2.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "http://mcp-fs.anonymous.modelcontextprotocol.io/sse"
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "云部署工具",
      "version": "2.4.0",
      "build_info": {
        "commit": "f7e8d9c2b1a0",
        "timestamp": "2023-12-05T08:45:00Z",
        "deployment_id": "remote-fs-deploy-456",
        "region": "us-west-2"
      }
    }
  }
}

Python包示例​

{
  "name": "io.github.example/weather-mcp",
  "description": "Python MCP服务器，用于天气数据访问",
  "repository": {
    "url": "https://github.com/example/weather-mcp",
    "source": "github",
    "id": "def456gh-ijkl-7890-mnop-qrstuvwxyz12"
  },
  "version": "0.5.0",
  "packages": [
    {
      "registry_type": "pypi",
      "registry_base_url": "https://pypi.org",
      "identifier": "weather-mcp-server",
      "version": "0.5.0",
      "runtime_hint": "uvx",
      "transport": {
        "type": "stdio"
      },
      "environment_variables": [
        {
          "name": "WEATHER_API_KEY",
          "description": "天气服务的API密钥",
          "is_required": true,
          "is_secret": true
        },
        {
          "name": "WEATHER_UNITS",
          "description": "温度单位（摄氏度、华氏度）",
          "default": "摄氏度"
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "poetry-publisher",
      "version": "1.8.3",
      "build_info": {
        "python_version": "3.11.5",
        "timestamp": "2023-11-28T16:20:00Z",
        "build_id": "pypi-weather-123",
        "dependencies_hash": "sha256:a9b8c7d6e5f4"
      }
    }
  }
}

NuGet (.NET) 包示例​

dnx` 工具从 .NET 10 SDK 的 Preview 6 版本开始随附提供。

{
  "name": "io.github.joelverhagen/knapcode-samplemcpserver",
  "description": "示例 NuGet MCP 服务器，用于生成随机数和随机天气",
  "repository": {
    "url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer",
    "source": "github",
    "id": "example-nuget-id-0000-1111-222222222222"
  },
  "version": "0.5.0",
  "packages": [
    {
      "registry_type": "nuget",
      "registry_base_url": "https://api.nuget.org",
      "identifier": "Knapcode.SampleMcpServer",
      "version": "0.5.0",
      "runtime_hint": "dnx",
      "transport": {
        "type": "stdio"
      },
      "environment_variables": [
        {
          "name": "WEATHER_CHOICES",
          "description": "用逗号分隔的天气描述列表，供随机选择。",
          "is_required": true,
          "is_secret": false
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "dotnet-publisher",
      "version": "8.0.100",
      "build_info": {
        "dotnet_version": "8.0.0",
        "timestamp": "2023-12-10T12:15:00Z",
        "configuration": "Release",
        "target_framework": "net8.0",
        "build_number": "20231210.1"
      }
    }
  }
}

复杂的 Docker 服务器及多个参数​

json
{
  "name": "io.github.example/database-manager",
  "description": "用于数据库操作的MCP服务器，支持多种数据库类型",
  "repository": {
    "url": "https://github.com/example/database-manager-mcp",
    "source": "github",
    "id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
  },
  "version": "3.1.0",
  "packages": [
    {
      "registry_type": "oci",
      "registry_base_url": "https://docker.io",
      "identifier": "example/database-manager-mcp",
      "version": "3.1.0",
      "transport": {
        "type": "stdio"
      },
      "runtime_arguments": [
        {
          "type": "named",
          "name": "--network",
          "value": "host",
          "description": "使用主机网络模式"
        },
        {
          "type": "named",
          "name": "-e",
          "value": "DB_TYPE={db_type}",
          "description": "要连接的数据库类型",
          "is_repeated": true,
          "variables": {
            "db_type": {
              "description": "数据库类型",
              "choices": [
                "postgres",
                "mysql",
                "mongodb",
                "redis"
              ],
              "is_required": true
            }
          }
        }
      ],
      "package_arguments": [
        {
          "type": "named",
          "name": "--host",
          "description": "数据库主机",
          "default": "localhost",
          "is_required": true
        },
        {
          "type": "named",
          "name": "--port",
          "description": "数据库端口",
          "format": "number"
        },
        {
          "type": "positional",
          "value_hint": "database_name",
          "description": "要连接的数据库名称",
          "is_required": true
        }
      ],
      "environment_variables": [
        {
          "name": "DB_USERNAME",
          "description": "数据库用户名",
          "is_required": true
        },
        {
          "name": "DB_PASSWORD",
          "description": "数据库密码",
          "is_required": true,
          "is_secret": true
        },
        {
          "name": "SSL_MODE",
          "description": "SSL连接模式",
          "default": "prefer",
          "choices": [
            "disable",
            "prefer",
            "require"
          ]
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "docker-buildx",
      "version": "0.12.1",
      "build_info": {
        "docker_version": "24.0.7",
        "timestamp": "2023-12-08T14:30:00Z",
        "platform": "linux/amd64,linux/arm64",
        "registry": "docker.io",
        "image_digest": "sha256:1a2b3c4d5e6f7890"
      }
    }
  }
}

具有远程和软件包选项的服务器​

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/hybrid-mcp",
  "description": "MCP server available as both local package and remote service",
  "repository": {
    "url": "https://github.com/example/hybrid-mcp",
    "source": "github",
    "id": "klm012no-pqrs-3456-tuvw-xyz789abcdef"
  },
  "version": "1.5.0",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "@example/hybrid-mcp-server",
      "version": "1.5.0",
      "runtime_hint": "npx",
      "transport": {
        "type": "stdio"
      },
      "package_arguments": [
        {
          "type": "named",
          "name": "--mode",
          "description": "Operation mode",
          "default": "local",
          "choices": [
            "local",
            "cached",
            "proxy"
          ]
        }
      ]
    }
  ],
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.anonymous.modelcontextprotocol.io/sse",
      "headers": [
        {
          "name": "X-API-Key",
          "description": "API key for authentication",
          "is_required": true,
          "is_secret": true
        },
        {
          "name": "X-Region",
          "description": "Service region",
          "default": "us-east-1",
          "choices": [
            "us-east-1",
            "eu-west-1",
            "ap-southeast-1"
          ]
        }
      ]
    },
    {
      "type": "streamable-http",
      "url": "https://mcp.anonymous.modelcontextprotocol.io/http"
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "hybrid-deployer",
      "version": "1.7.2",
      "build_info": {
        "timestamp": "2023-12-03T11:00:00Z",
        "deployment_strategy": "blue-green",
        "npm_version": "10.2.4",
        "node_version": "20.10.0",
        "service_endpoints": {
          "sse": "deployed",
          "streamable": "deployed"
        }
      }
    }
  }
}

MCP捆绑包（MCPB）示例​

{
  "name": "io.modelcontextprotocol/text-editor",
  "description": "MCP 捆绑服务器，提供高级文本编辑功能",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/text-editor-mcpb",
    "source": "github"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registry_type": "mcpb",
      "registry_base_url": "https://github.com",
      "identifier": "https://github.com/modelcontextprotocol/text-editor-mcpb/releases/download/v1.0.2/text-editor.mcpb",
      "version": "1.0.2",
      "file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "mcpb-publisher",
      "version": "1.0.0",
      "build_info": {
        "timestamp": "2023-12-02T09:15:00Z",
        "bundle_format": "mcpb-v1"
      }
    }
  }
}

此示例展示了一个MCPB（MCP Bundle）包，该包：

  • 托管在GitHub Releases（一个被列入许可名单的提供者）
  • 包含用于完整性验证的SHA-256哈希值
  • 可以被支持MCPB的MCP客户端直接下载和执行

在CLI工具中嵌入MCP​

某些CLI工具捆绑了一个MCP服务器，但没有单独的MCP包或公共仓库。在这些情况下，可以通过指向主机CLI包并提供package_arguments和runtime_hint（如有需要）来启动MCP服务器，从而复用现有的packages结构。

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.snyk/cli-mcp",
  "description": "MCP server provided by the Snyk CLI",
  "status": "active",
  "version": "1.1298.0",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "snyk",
      "version": "1.1298.0",
      "transport": {
        "type": "stdio"
      },
      "package_arguments": [
        { "type": "positional", "value": "mcp" },
        {
          "type": "named",
          "name": "-t",
          "description": "Transport type for MCP server",
          "default": "stdio",
          "choices": ["stdio", "sse"]
        }
      ]
    }
  ]
}

具有自定义安装路径的服务器​

对于遵循自定义安装路径的MCP服务器或嵌入在没有独立软件包的应用程序中的服务器，请使用 website_url 字段引导用户查看设置文档：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
  "description": "MCP server embedded in a Desktop app",
  "status": "active",
  "website_url": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
  "version": "0.1.0"
}

已弃用的服务器示例​

json
{
  "name": "io.github.example/old-weather",
  "description": "遗留的天气服务 - 已弃用：对于新项目请使用 weather-v2",
  "status": "已弃用",
  "repository": {
    "url": "https://github.com/example/old-weather",
    "source": "github",
    "id": "legacy-abc123-def456-789012-345678-901234567890"
  },
  "version": "0.9.5",
  "packages": [
    {
      "registry_type": "npm",
      "registry_base_url": "https://registry.npmjs.org",
      "identifier": "@legacy/old-weather-server",
      "version": "0.9.5",
      "transport": {
        "type": "stdio"
      },
      "environment_variables": [
        {
          "name": "WEATHER_API_KEY",
          "description": "天气 API 密钥",
          "is_required": true,
          "is_secret": true
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "遗留发布工具",
      "version": "0.8.1",
      "build_info": {
        "timestamp": "2023-06-15T09:30:00Z",
        "deprecation_notice": "此发布工具已弃用。对于新项目请使用 npm-publisher v2.0+。",
        "maintenance_mode": true,
        "final_version": true
      }
    }
  }
}