mcp -for-oscal

This MCP server exposes tools to assist AI agents in working with OSCAL content. It bundles a curated set of OSCAL models, templates, and related resources so that you can query model schemas, generate minimal OSCAL artifacts, and reason about OSCAL structures without needing external network access. The server is designed to run locally via the standard MCP stdio transport, making it convenient for experimentation with agents like kiro-cli or other MCP-enabled assistants. Tools and capabilities are described under the server’s internal toolset, which is implemented in the src/mcp_server_for_oscal/tools directory. To interact with the server, start it using Python, then connect your AI agent through MCP-compatible commands to invoke the bundled tools (e.g., listing OSCAL models, fetching schemas, or generating minimal OSCAL templates).

Prerequisites:

• Python 3.8+ (recommended 3.9+)
• Git (optional, for cloning the repository)

Install and run from source:

# 1) Clone the repository
git clone https://github.com/awslabs/mcp-server-for-oscal.git
cd mcp-server-for-oscal

# 2) (Optional) Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows use: .\.venv\Scripts\activate

# 3) Install dependencies (adjust if a requirements file is present; this may vary by release)
python -m pip install -r requirements.txt || python -m pip install -r dev-requirements.txt

# 4) Install the package in editable mode (if applicable)
python -m pip install -e .

# 5) Run the MCP server
python -m mcp_server_for_oscal

If you prefer a packaged install, you can also install via pip (from PyPI) and then run the module as above:

pip install mcp-server-for-oscal
python -m mcp_server_for_oscal

Notes:

• Ensure your environment has network access if you need to pull additional assets; otherwise the server relies on bundled content.
• The server defaults to stdio MCP transport; if you plan to run with alternative transports, refer to the MCP spec and your agent’s integration guide.

Tips and considerations:

• The MCP server validates bundled content against SHA-256 manifests at startup for integrity; any mismatch will prevent startup.
• By default, do not enable streaming HTTP transport due to lack of built-in transport security in this release.
• Tools are located in src/mcp_server_for_oscal/tools; explore to understand available operations such as list_oscal_models, get_oscal_schema, and generate OSCAL templates.
• If you need to override bundled content with local OSCAL assets, set MCP_OSCAL_CONTENT_DIR to point at your directory before starting the server.
• If startup fails, check the logs for content verification errors or missing dependencies, and verify you’re using a compatible Python version (3.8+).