MCP Server for OSCAL

OSCAL MCP 服务

为你喜爱的 AI Agent 提供即时 OSCAL 专业知识

一个模型上下文协议（MCP）服务，为 AI 助手（Claude、Cline、Kiro、Claude Code 等）提供工具，以便处理美国国家标准与技术研究院（NIST）的开放安全控制评估语言（OSCAL）。和许多早期采用者一样，我们需要帮助实现 OSCAL 概念验证，以向业务相关方展示其价值。或许是因为公开领域的示例数量有限，我们发现仅依靠 AI Agent/大模型，通常会对 OSCAL 给出不一致的结果。这个 MCP 服务中的工具为我们的使用场景缓解了这一问题，希望也能为你做到这一点。

提示

若要开始使用，请参阅下方的安装。

目录

• 功能：工具覆盖的内容、仅限本地的运行模式和完整性检查
• 什么是 OSCAL？和什么是 MCP？：背景介绍
• 如何使用 / 示例：涵盖模型、模板、目录和 AWS 组件定义的示例会话
• 安装：适用于 Claude Desktop 的一键式 MCP Bundle（.mcpb），或提供 Kiro、Claude Desktop 和 VS Code 配置的 PyPI 软件包
• 使用你自己的 OSCAL 内容：OSCAL_DOCUMENTS_DIR 和存储设置
• OSCAL Agent：独立的 Strands/Bedrock Agent、会话和对话管理
• 开发、安全、已知限制、相关项目、许可证

功能

此 MCP 服务提供的工具旨在帮助你首选的 AI 助手准确、权威地提供有关 OSCAL 架构、模型、用例、要求和实现的指导。你无需了解这些工具即可使用它们，详情请参阅 tools 目录。

此服务轻量，旨在无需额外设置即可在本地运行。默认情况下，它使用 stdio 协议进行 MCP 传输。请勿尝试通过 streamable-http 传输使用此服务，因为我们尚未实现传输安全或身份验证。

默认工具不应连接到任何远程服务或资源——所有必需内容都随服务一同打包。作为一项安全措施，我们为打包内容实现了基本的文件完整性验证。在构建时，我们会生成清单，其中包含打包的 OSCAL 架构和预构建内容数据库的 SHA-256 哈希值。每次服务启动时，都会根据清单验证两者。架构不匹配会导致错误并阻止启动；数据库不匹配会导致服务丢弃打包的数据库并以空数据库启动。

这些工具涵盖 OSCAL 架构和模型元数据、Metaschema 允许值、约束、引用和定义查找以及源代码读取（get_allowed_values、get_constraints、find_references_to、get_definition、get_metaschema_source）、多层级内容验证、Component Definition 导航、对所有 OSCAL 模型类型（目录、配置文件、SSP、评估计划和结果、POA&M、映射集合）的查询、列表和全文搜索、社区资源以及文档。搜索工具采用搜索/获取配对形式：text_search_oscal 返回元素 ID 和 parentDocumentUuid，由 get_child_element 解析；query_oscal_documentation 返回分页的 {title, snippet} 段落，本地页面会附带 docId，供 get_oscal_documentation 按行范围读取。结果中不会包含文件系统路径。完整列表请参阅 tools README。

除了 MCP 服务，该软件包还包含一个使用 Strands Agents 构建的独立 OSCAL Agent。请参阅下方的 OSCAL Agent 部分。

什么是 OSCAL？

OSCAL（开放安全控制评估语言）是 NIST 开发的一套框架无关、供应商中立、机器可读的架构，用于描述 GRC（治理、风险、合规）制品的完整生命周期，涵盖从控制到补救计划的各个环节。OSCAL 通过用基于标准的结构化数据格式取代电子文档（电子表格、PDF 等），实现 GRC 工作流自动化。要进一步了解 OSCAL，请先安装此 MCP 服务，然后向 AI 提问。或者参阅 OSCAL 官方网站。

什么是 MCP？

MCP（模型上下文协议）是一种用于将 AI 应用连接到外部系统的开源标准。可以把 MCP 看作 AI 应用的 USB-C 接口。正如 USB-C 提供了连接电子设备的标准化方式，MCP 也提供了连接 AI 应用和外部系统的标准化方式。

使用方法 / 示例

以下示例使用 kiro-cli 创建，但也适用于任何支持 MCP 服务的 AI 助手。

示例 1：了解可用的 OSCAL 模型

 % kiro-cli

> /tools trust get_oscal_schema list_oscal_models list_oscal_resources


Tools '@oscal/get_oscal_schema', '@oscal/list_oscal_models', '@oscal/list_oscal_resources' are now trusted. I will not ask for confirmation before running these tools.


> How many GA OSCAL models are there? 


> I'll check the available OSCAL models to find out how many are in GA (Generally Available) status.
Running tool list_oscal_models with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.1s

> There are 8 GA OSCAL models:

Control Layer (3):
- Catalog
- Profile  
- Mapping Collection

Implementation Layer (2):
- Component Definition
- System Security Plan (SSP)

Assessment Layer (3):
- Assessment Plan (SAP)
- Assessment Results (SAR)
- Plan of Action and Milestones (POA&M)

All of these models have "GA" (Generally Available) status, meaning they are stable and ready for production use.
 ▸ Time: 8s

示例 2：生成 OSCAL 模板

> generate a minimum, valid, OSCAL mapping in JSON for use as a template.

> I'll help you create a minimal, valid OSCAL mapping in JSON. Let me first check what OSCAL models are available to understand the structure.
Running tool list_oscal_models with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.1s

> Now let me get the schema for the mapping-collection model to understand its structure:
Running tool get_oscal_schema with the param (from mcp server: oscal)
 ⋮  {
 ⋮    "model_name": "mapping-collection",
 ⋮    "schema_type": "json"
 ⋮  }
 - Completed in 0.14s

> Based on the schema, I'll create a minimal, valid OSCAL mapping collection template. Here's the absolute minimum required structure:
I'll create the following file: ./oscal-mapping-template.json (using tool: write)
Purpose: Create minimal OSCAL mapping collection template

+     1: {
+     2:   "mapping-collection": {
+     3:     "uuid": "12345678-1234-4567-8901-123456789012",
+     4:     "metadata": {
+     5:       "title": "Sample Mapping Collection",
+     6:       "last-modified": "2026-01-06T20:46:28.034Z",
+     7:       "version": "1.0",
+     8:       "oscal-version": "1.2.0"
+     9:     },
+    10:     "provenance": {
+    11:       "method": "human",
+    12:       "matching-rationale": "semantic",
+    13:       "status": "draft",
+    14:       "mapping-description": "Sample mapping between two control frameworks"
+    15:     },
+    16:     "mappings": [
+    17:       {
+    18:         "uuid": "87654321-4321-7654-1098-210987654321",
+    19:         "source-resource": {
+    20:           "type": "catalog",
+    21:           "href": "https://example.com/source-catalog.json"
+    22:         },
+    23:         "target-resource": {
+    24:           "type": "catalog", 
+    25:           "href": "https://example.com/target-catalog.json"
+    26:         },
+    27:         "maps": [
+    28:           {
+    29:             "uuid": "11111111-2222-3333-4444-555555555555",
+    30:             "relationship": "equivalent",
+    31:             "sources": [
+    32:               {
+    33:                 "type": "control",
+    34:                 "id-ref": "ac-1"
+    35:               }
+    36:             ],
+    37:             "targets": [
+    38:               {
+    39:                 "type": "control",
+    40:                 "id-ref": "access-control-policy"
+    41:               }
+    42:             ]
+    43:           }
+    44:         ]
+    45:       }
+    46:     ]
+    47:   }
+    48: }

Creating: ./oscal-mapping-template.json
 - Completed in 0.8s

> I've created a minimal, valid OSCAL mapping collection template at ./oscal-mapping-template.json. This template includes:

Required elements:
- uuid: Unique identifier for the mapping collection
- metadata: Document metadata with title, last-modified timestamp, version, and OSCAL version
- provenance: Mapping methodology information including method, matching rationale, status, and description
- mappings: Array containing at least one mapping with:
  - uuid: Mapping identifier
  - source-resource and target-resource: References to the catalogs being mapped
  - maps: Array with mapping entries showing relationships between controls

Key features:
- Uses placeholder UUIDs (replace with actual UUIDs in production)
- Maps a source control "ac-1" to target control "access-control-policy" with "equivalent" relationship
- Includes minimal required fields only
- Valid JSON structure conforming to OSCAL 1.2.0 schema

You can customize this template by:
- Replacing placeholder UUIDs with real ones
- Updating the resource URLs to point to actual catalogs
- Adding more mapping entries in the maps array
- Modifying control IDs and relationships as needed
 ▸ Time: 21s

示例 3：发现开源 OSCAL 目录

> What are some open source OSCAL catalogs?

Running tool list_oscal_resources with the param (from mcp server: oscal)
 ⋮  {}
 - Completed in 0.51s

> Based on the OSCAL community resources, here are some notable open source OSCAL catalogs:

## Government/Official Catalogs

Australian Cyber Security Centre (ACSC)
- Information Security Manual (ISM) controls in OSCAL format
- Essential Eight Maturity Levels (ML1, ML2, ML3)
- Available at: https://www.cyber.gov.au/ism/oscal

CMS Acceptable Risk Safeguards (ARS)
- Tailored NIST SP 800-53 controls for Centers for Medicare and Medicaid Services
- Available at: https://github.com/CMSgov/ars-machine-readable

GovTech Singapore
- ICT&SS Policy catalog and profile for low-risk systems
- Available at: https://github.com/GovtechSG/tech-standards

## Industry/Standards Organizations

Center for Internet Security (CIS)
- CIS Critical Security Controls (formerly Top 18/20)
- Available at: https://github.com/CISecurity/CISControls_OSCAL/

Cloud Security Alliance (CSA)
- Cloud Controls Matrix v4 in OSCAL format
- Available at: https://cloudsecurityalliance.org/artifacts/ccm-machine-readable-bundle-json-yaml-oscal/

NIST SP 800-171 (Community)
- Maintained by Fathom5
- Available at: https://github.com/FATHOM5/oscal/tree/main/content/SP800-171/oscal-content

## Community Collections

CivicActions Component Definitions
- Cloud services, software, security and privacy controls
- Available at: https://github.com/CivicActions/oscal-component-definitions

RedHat OSCAL Content
- Component definitions: https://github.com/RedHatProductSecurity/oscal-component-definitions
- Custom profiles: https://github.com/RedHatProductSecurity/oscal-profiles

Brad Hards ISM Catalog
- Australian Government ISM controls (community version)
- Available at: https://github.com/bradh/ism-oscal

These catalogs provide ready-to-use OSCAL content for various compliance frameworks and can serve as templates or starting points for your own OSCAL implementations.
 ▸ Time: 15s

示例 4：查询 Component Definition，了解 AWS 服务信息

[OSCAL] > what components are available for Cognito?

Running tool list_components with the param (from mcp server: oscal-dev)
 ⋮  {}
 - Completed in 0.49s

> There are 3 Cognito-related components available:

1. Cognito Identity - from "Cognito Identity Pools" component definition
2. Cognito Sync - from "Amazon Cognito Sync" component definition  
3. Cognito Identity Provider - from "Amazon Cognito Identity User Pools" component definition

 ▸ Time: 7s

[OSCAL] > show me the names and IDs from all 3 components

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "7fd5d354-6ec4-4f8e-8c5f-2904086bb597"
 ⋮  }
Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "a1d82e1d-3733-41f4-bc09-90ab47b9e82f"
 ⋮  }
Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "2519deaf-4612-4c70-aba2-d9080ae3c816"
 ⋮  }
 - Completed in 0.13s

 - Completed in 0.6s

 - Completed in 0.6s

> 1. Cognito Sync
- Service ID: Cognito Sync
- API Endpoint Prefix: cognito-sync
- ARN Namespace: cognito-sync

2. Cognito Identity Provider
- Service ID: Cognito Identity Provider
- API Endpoint Prefix: cognito-idp
- ARN Namespace: cognito-idp

3. Cognito Identity
- Service ID: Cognito Identity
- API Endpoint Prefix: cognito-identity
- ARN Namespace: cognito-identity

 ▸ Time: 12s

[OSCAL] > show me everything in the EC2 component definition

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "component_definition_filter": "Elastic Compute Cloud (EC2)",
 ⋮    "query_type": "all"
 ⋮  }
 - Completed in 0.14s

> The EC2 component definition contains 1 component:

Component: EC2
- UUID: 66345eb9-7c0d-435c-b2b5-675fd977de80
- Type: service
- Description: Empty

Properties:
- Service ID: EC2
- Version: 2016-11-15
- Availability: REGIONAL and ZONAL
- Full Name: Elastic Compute Cloud (EC2)
- API Endpoint Prefix: ec2
- ARN Namespace: ec2

Regional Availability (34 regions):
Africa (Cape Town), Asia Pacific (Hong Kong, Tokyo, Seoul, Osaka, Mumbai, Hyderabad, Singapore, Sydney, Jakarta, Melbourne, Malaysia), Canada (Central, Calgary), China (Beijing, Ningxia), 
Europe (Frankfurt, Zurich, Stockholm, Milan, Spain, Ireland, London, Paris), Israel (Tel Aviv), Middle East (UAE, Bahrain), South America (Sao Paulo), US East (N. Virginia, Ohio), AWS 
GovCloud (US-East, US-West), US West (N. California, Oregon)

 ▸ Time: 10s

[OSCAL] > what's the ID of the Jakarta region?

> Based on the EC2 component data I just retrieved, the Jakarta region's resource fragment ID is:

8041109b-0a0b-46cc-bddb-91d703667637

This is the UUID for the "Asia Pacific (Jakarta)" region component.

 ▸ Time: 3s

[OSCAL] > get the region ID from that component

Running tool query_component_definition with the param (from mcp server: oscal-dev)
 ⋮  {
 ⋮    "query_type": "by_uuid",
 ⋮    "query_value": "8041109b-0a0b-46cc-bddb-91d703667637"
 ⋮  }
 - Completed in 0.13s

> The region ID for Jakarta is: ap-southeast-3

 ▸ Time: 7s

[OSCAL] > /quit

安装

按照以下说明，为你偏好的 IDE、AI Agent、聊天机器人等配置 MCP 服务。该服务通过两种方式分发：

• MCP Bundle（.mcpb）：适用于 Claude Desktop 等兼容 MCPB 的桌面应用的单文件、一键安装包。每个 GitHub 版本发布都附带此安装包。请参阅下文的 MCP Bundle。
• PyPI 上的 Python 包：适用于任何 MCP 客户端。uvx 命令（如下所示）会在启动时自动从 PyPI 下载最新版本的服务。

说明

若要改为配置开发环境，请参阅 DEVELOPING.md

MCP Bundle

MCP Bundle 会将服务、其清单和锁定的依赖版本打包到一个文件中。宿主应用会为你安装 Python 和依赖项，因此无需满足下方的先决条件。

1. 从最新版本发布下载 mcp-server-for-oscal-<version>.mcpb。
2. 使用兼容 MCPB 的应用打开该文件。在 Claude Desktop 中，双击该文件或将其拖到 Settings > Extensions，然后点击 Install。
3. 你也可以配置扩展的设置。所有设置均为可选；默认配置会完全在本地运行，并使用捆绑的内容。

设置	环境变量	说明
OSCAL 文档目录	OSCAL_DOCUMENTS_DIR	用于与捆绑内容一同编入索引的自有 OSCAL JSON 文件目录。请参阅使用自有 OSCAL 内容。
允许远程 URI	OSCAL_ALLOW_REMOTE_URIS	允许工具从 http/https URI 获取 OSCAL 内容。默认关闭。
Bedrock 知识库 ID	OSCAL_KB_ID	用于文档查询的 Amazon Bedrock 知识库。留空则使用捆绑的本地文档搜索。
AWS 配置文件 / AWS 区域	AWS_PROFILE / AWS_REGION	用于查询 Bedrock 知识库的凭证和区域。
日志级别	LOG_LEVEL	DEBUG、INFO（默认）、WARNING 或 ERROR。

下方的 uvx 配置会在启动时获取最新的 PyPI 版本，而 Bundle 会保持在你安装时的版本。若要升级，请下载并安装较新版本发布中的 .mcpb。

先决条件

以下要求适用于 PyPI 包（下方所有使用 uvx 的配置），不适用于 MCP Bundle。

• Python 的 uv 包管理器（安装说明）
• Python 3.13 或更高版本（uv python install 3.14）。该服务可能适用于更高版本的 Python，但目前我们只测试了 3.13 和 3.14。

配置 IDE 和 AI 工具

此服务通过 stdio（标准输入/输出）通信，可与支持 Model Context Protocol 的各种 IDE 和 Agent 工具集成。下方的配置示例适用于你偏好的 IDE、聊天机器人或 Agent。

配置格式

大多数兼容 MCP 的工具使用 FastMCP 文档中介绍的 JSON 配置格式。基本结构如下：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

对于 MCP 服务的常规运行时使用，无需其他配置。如有需要，可按照 FastMCP 文档中的说明，在 "env": {} 对象中配置运行时环境变量。可用选项请参阅文件 dotenv.example。

说明

仅在开发环境中需要 dotenv 文件。

Kiro 配置

如需了解其他选项，请参阅 Kiro 的 MCP 文档。将以下内容添加到 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "*"
      ]
    }
  }
}

Claude Desktop

最简单的安装方式是使用 MCP Bundle。Claude Desktop 会为你管理 Python 和依赖项，还可以配置可选设置，例如指定存放你自己的 OSCAL 文档的目录。

或者，在 Claude Desktop 中打开 Settings > Developer > Edit Config，并将以下内容添加到 claude_desktop_config.json（macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

VS Code

运行 MCP: Open User Configuration 命令，该命令会打开用户配置文件夹中的 mcp.json 文件。然后，你可以手动将服务配置添加到文件中。有关其他选项和详细信息，请参阅 VSCode/Copilot 文档。

{
  "servers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"]
    }
  }
}

使用你自己的 OSCAL 内容

默认情况下，服务附带捆绑的 OSCAL 内容（AWS 组件定义、OSCAL 文档和架构）。你也可以将服务指向存放自己 OSCAL JSON 文件的目录——这些文件可以是目录、SSP、配置文件、评估计划、评估结果、POA&M 或映射集合。服务会在启动时为这些文件建立索引，并通过所有查询和列表工具提供这些内容。

将 OSCAL_DOCUMENTS_DIR 环境变量设为 OSCAL 内容目录的路径。路径可以是绝对路径，也可以是相对于服务程序包目录的路径。例如，在 MCP 配置中：

{
  "mcpServers": {
    "oscal": {
      "command": "uvx",
      "args": ["mcp-server-for-oscal@latest"],
      "env": {
        "OSCAL_DOCUMENTS_DIR": "/path/to/your/oscal/files"
      }
    }
  }
}

服务会递归扫描该目录中的 .json 文件，并为找到的所有有效 OSCAL 文档建立索引。你的内容会与捆绑内容合并，两者都可以在同一会话中查询。目录中的 Markdown（.md）文件会作为文档建立索引：query_oscal_documentation 会搜索这些文件（配置 Bedrock 知识库时也会搜索），而 get_oscal_documentation 会根据 docId 读取这些文件。

以下环境变量用于控制 OSCAL 存储行为：

变量	默认值	描述
OSCAL_DOCUMENTS_DIR	(empty)	存放你自己的 OSCAL JSON 文件的目录。为空时不会扫描。
OSCAL_STORE_DB_PATH	(empty)	持久化 SQLite 数据库的路径。设置后，索引会在服务重启后复用，而不是每次都重新构建。
OSCAL_STORE_CACHE_SIZE	100	内存 LRU 缓存中保留的已解析 OSCAL 文档的最大数量。

提示

如果你有大量 OSCAL 文档，建议设置 OSCAL_STORE_DB_PATH。后续启动时，服务只需为新增或已更改的文件建立索引。由旧版本服务创建的数据库会在首次启动时原位升级。

OSCAL Agent

除了 MCP 服务，该程序包还包含一个使用 Strands Agents 构建的独立 OSCAL Agent。该 Agent 使用与 MCP 服务相同的工具，可以直接运行：

# Via entry point
oscal-agent

# Or via module
python -m mcp_server_for_oscal.oscal_agent

该 Agent 需要访问 AWS Bedrock，并使用与 MCP 服务相同的配置环境变量。

会话持久化

该 Agent 支持会话持久化，因此调用之间可以保留对话历史和 Agent 状态。可选择本地文件系统或 Amazon S3 存储：

# File-based session storage (new session)
oscal-agent --session-storage file

# Resume a previous session
oscal-agent --session-storage file --session-id <your-session-id>

# S3-based session storage
oscal-agent --session-storage s3 --session-s3-bucket my-bucket

启用会话存储后，如果未设置 --session-id，系统会自动生成并显示一个 UUID，方便你稍后恢复会话。也可以通过环境变量设置会话默认值（参见 DEVELOPING.md）。

对话管理

对于长时间运行的工作流，你可以选择一种对话管理器，以控制 Agent 如何维护其上下文窗口：

# Summarize older messages to keep context manageable
oscal-agent --session-storage file --conversation-manager summarizing

# Sliding window (SDK default behavior)
oscal-agent --conversation-manager sliding-window

# No conversation management
oscal-agent --conversation-manager null

现有工具和功能涵盖了多种用例，但距离全面支持_还差得很远_。欢迎通过 GitHub issue 分享反馈、功能请求、问题或 Bug 报告。我们也期待并欢迎你直接参与贡献。

开发

请参阅 DEVELOPING 了解如何开始。

安全性

更多信息请参阅 CONTRIBUTING。

已知限制

• 由于 ChatGPT 对 MCP 的支持有限，目前还无法将此 MCP 服务与 ChatGPT 配合使用。
• streamable-http 传输尚未实现身份验证或传输安全。生产工作负载请使用 stdio。

相关项目

此 MCP 服务捆绑了适用于 AWS 服务的实验性组件定义。你可以在 AWS Labs 项目 OSCAL Content for AWS Services 中找到这些内容。

MCP Server for OSCAL 使用 oscal-bindings 提供带类型的 OSCAL 模型，包括模型级内容验证。

许可证

本项目采用 Apache-2.0 许可证。