ministack-mcp

Your local AWS runtime for AI agents. A Model Context Protocol server that
lets any IDE-resident AI agent (Claude Desktop, Cursor, Continue, Devin,
Cline, …) act against a local MiniStack environment —
deploy code, create infrastructure, run AWS CLI commands, run smoke tests,
export live state as IaC — and answer deterministic, version-pinned questions
about MiniStack's emulated services, supported operations, config vars, and
parity status.

The knowledge side is backed by catalog.json + parity.json, generated once
at build time from the MiniStack codebase, so those answers are stable, fast,
and tied to the exact MiniStack version you have running. The action side talks
to the live emulator at MINISTACK_ENDPOINT_URL.

You say "test my Lambda." The agent reads your code, deploys it, invokes it, and
tells you if it works. You say "apply my Terraform." The agent runs it against
the local environment and shows you what happened. You never think about
MiniStack — you think about your code.

• Developer: "Test my Lambda function" → deploys it locally, invokes it, reports pass/fail
• Tester: "Run my test suite" → spins up infrastructure, runs tests, cleans up
• SRE: "Apply my Terraform" → applies it locally, verifies resources, reports status

Install

pipx install ministack-mcp
# or
uvx ministack-mcp

Set MINISTACK_ENDPOINT_URL (default http://localhost:4566) if you run
MiniStack on a non-default port.

Tools exposed

Around 40 tools, grouped by what they do:

Knowledge (from catalog.json / parity.json) — list_services,
get_service, is_operation_supported, search_operations, list_config_vars,
get_config_var, get_endpoint_info, find_service_for_use_case,
compare_with_aws.

State & health — ministack_version, ministack_health, ministack_reset,
reset_and_verify, validate_endpoint, get_setup_status, get_docker_status.

Act on the live emulator — aws_execute (any AWS CLI command),
create_resource, delete_resource, list_resources, describe_resource,
invoke_lambda, put_s3_object, query_dynamodb, send_sqs_message,
publish_sns.

Test & generate — run_smoke_test, check_terraform_coverage,
check_sdk_coverage, generate_test_fixture, scaffold_architecture,
export_setup, diff_environments, explain_error, suggest_next_steps.

Docs (also exposed as ministack://docs/* MCP resources) — get_readme,
get_quickstart, get_docker_doc, get_terraform_doc, get_testing_doc,
get_faq_doc, get_migration_guide.

IDE configuration

Claude Desktop / Claude Code

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

{
  "mcpServers": {
    "ministack": {
      "command": "uvx",
      "args": ["ministack-mcp"],
      "env": {
        "MINISTACK_ENDPOINT_URL": "http://localhost:4566"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json:

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

Continue (.continuerc or ~/.continue/config.json)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["ministack-mcp"]
        }
      }
    ]
  }
}

Devin

Devin adds MCP servers from its web UI, not a local config file:

1. Go to Settings → Connections → MCP servers and click Add a custom MCP
   (requires the Manage MCP Servers permission).
2. Choose the STDIO transport and set Command uvx and Args
   ministack-mcp. Add MINISTACK_ENDPOINT_URL to the environment if you run
   MiniStack on a non-default port.

Cline (VS Code extension)

VS Code settings, cline.mcpServers:

{
  "ministack": {
    "command": "uvx",
    "args": ["ministack-mcp"]
  }
}

Codex configuration

Codex uses the same local MCP contract as the other agents in this repo.
Keep MINISTACK_ENDPOINT_URL pointed at the MiniStack instance you want to use.

Codex CLI

Register the server with the local uvx entry point:

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

If you need a non-default backend:

export MINISTACK_ENDPOINT_URL=http://localhost:4566
uvx ministack-mcp

Codex app

Use the same MCP server definition in the Codex app settings:

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

If the app exposes a separate MCP settings screen, add the same command and
args pair there.

Regenerating the catalog

When MiniStack itself changes, regenerate the catalog before publishing a new
release of ministack-mcp:

python build_catalog.py

This rewrites catalog.json in place. parity.json is hand-curated and is
never touched by the generator.

How it works

1. build_catalog.py walks ministack/services/*.py and extracts AWS
   operation names from action dicts, equality compares, match/case
   blocks, URL-path dispatch dicts, and module docstrings.
2. It also walks all of ministack/ for os.environ.get / os.getenv /
   os.environ[...] to inventory every env var the emulator reads.
3. The result, catalog.json, is shipped with the package.
4. parity.json adds curated status (full / partial / stub / paid /
   data-plane / unsupported), real-backend flags, persistence, and gotchas.
5. server.py reads both files at import time and exposes the tools above
   over MCP stdio. The knowledge tools answer from the catalog; the action
   tools (aws_execute, invoke_lambda, create_resource, …) talk to the
   live emulator at MINISTACK_ENDPOINT_URL.

License

MIT.