base2-mcp

MCP server for Base2 open-source AWS tools — documentation, guidance, and CLI execution.

Supported Tools

Quick Start

Cursor IDE (Recommended)

Add to your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "base2": {
      "command": "uvx",
      "args": ["--upgrade", "base2-mcp"]
    }
  }
}

No manual install needed — uvx fetches the package from PyPI automatically and --upgrade ensures you always get the latest version on server restart.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "base2": {
      "command": "uvx",
      "args": ["--upgrade", "base2-mcp"]
    }
  }
}

Alternative: pin to a specific version

If you need a stable version that won't change unexpectedly:

{
  "mcpServers": {
    "base2": {
      "command": "uvx",
      "args": ["base2-mcp==0.1.0"]
    }
  }
}

Prerequisite: uv

uvx is part of uv, a fast Python package manager. Install it with:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

What It Does

This MCP server gives AI agents two capabilities for each tool:

1. Documentation — Embedded docs with CLI usage, configuration, examples, and best practices. The agent can read these to understand any tool without you explaining it.

2. CLI Execution — Wrapper tools that run the actual CLI commands (cfhighlander cfcompile, shelvery ebs create_backups, bastion launch, etc.) and return structured output.

Available MCP Tools

Discovery:

• list_base2_tools — Overview of all 6 tools
• get_tool_docs — Detailed documentation for a specific tool

cfhighlander:

• cfhighlander_docs / cfhighlander_compile / cfhighlander_publish / cfhighlander_test / cfhighlander_validate

shelvery:

• shelvery_docs / shelvery_create_backups / shelvery_clean_backups / shelvery_pull_shared_backups

cfn-guardian:

• guardian_docs / guardian_compile / guardian_deploy / guardian_show_alarms / guardian_show_resources

monitorable:

• monitorable_docs / monitorable_audit

cfn-vpn:

• cfn_vpn_docs / cfn_vpn_init / cfn_vpn_modify / cfn_vpn_routes / cfn_vpn_sessions

bastion-cli:

• bastion_docs / bastion_launch / bastion_connect / bastion_terminate / bastion_port_forward

Prerequisites

The MCP server itself only needs Python 3.11+ and the mcp package. The CLI tools it wraps need to be installed separately — the server will tell the agent if a tool is missing and how to install it.

Development

# Install dependencies
pip install -r requirements.txt -r requirements-dev.txt

# Run tests
pytest tests/ -v

# Run the server locally (stdio mode)
python src/app.py

Architecture

base2-mcp/
├── src/
│   ├── app.py                    # FastMCP entry point (stdio transport)
│   ├── docs/                     # Embedded markdown documentation
│   │   ├── __init__.py           # Doc loader utility
│   │   ├── cfhighlander.md
│   │   ├── shelvery.md
│   │   ├── guardian.md
│   │   ├── monitorable.md
│   │   ├── cfn_vpn.md
│   │   └── bastion.md
│   ├── executor/
│   │   └── cli_runner.py         # Shared subprocess executor
│   └── tools/                    # One module per tool
│       ├── overview_tools.py     # list_base2_tools, get_tool_docs
│       ├── cfhighlander_tools.py
│       ├── shelvery_tools.py
│       ├── guardian_tools.py
│       ├── monitorable_tools.py
│       ├── cfn_vpn_tools.py
│       └── bastion_tools.py
├── tests/                        # pytest suite (56 tests)
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txt