AWS Notebook Runner MCP
Allows running Jupyter notebooks on temporary AWS compute resources (EC2) managed via Systems Manager (SSM), with S3 artifact storage, cost estimation, and automatic cleanup.
Enables inspection, estimation, planning, and execution of Jupyter notebooks on AWS infrastructure, with support for .ipynb files and nbconvert.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AWS Notebook Runner MCP Run my analysis notebook with dry-run first"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AWS Notebook Runner MCP
Run Jupyter notebooks on temporary AWS compute through an MCP server, with dry-run planning, guardrails, progress reporting, cost estimates, S3 artifacts, and automatic cleanup.
This is not Google Colab automation and it does not bypass provider limits. It is an AI-facing wrapper for AWS notebook execution. The current working execution backend is EC2 + Systems Manager (SSM). A SageMaker Notebook Jobs backend is included for planning and future execution, but it depends on your AWS account quotas.
This project is not affiliated with, endorsed by, or sponsored by Amazon Web Services. AWS and Amazon SageMaker are trademarks of Amazon.com, Inc. or its affiliates.
AI-Readable Manifest
This repository includes manifest.0, a Zero Lang description of the MCP server's purpose, capabilities, and boundaries. It is intended to help AI agents understand that this package is an AWS notebook execution runner with guardrails, not Google Colab automation or a provider-limit bypass tool.
Related MCP server: AWS FinOps MCP Server
What It Can Do
Inspect a local
.ipynbunder an allowlisted local root.Estimate compute cost before launch.
Build dry-run plans without starting paid compute.
Start a temporary EC2 instance for a notebook run.
Execute the notebook through SSM with
nbconvert.Upload the executed notebook and artifacts to S3.
Report progress, elapsed time, ETA, SSM status, EC2 state, artifacts, and current compute cost estimate.
Terminate the EC2 instance automatically after completion.
Refuse paid compute unless both an environment flag and confirmation token are provided.
What It Does Not Do
It does not create or broaden IAM permissions.
It does not manage arbitrary AWS resources.
It does not open SSH ports.
It does not provide exact cell-level progress yet.
It does not include memory/filesystem metrics unless you add SSM snapshots or CloudWatch Agent support.
It does not make AWS quota requests.
Install
From PyPI, after publication:
pip install "aws-notebook-runner-mcp[aws]"From a local checkout:
python3 -m venv .venv
.venv/bin/pip install -e ".[aws,test]"Run the MCP server:
aws-notebook-runner-mcpRequired AWS Resources
You need:
An S3 bucket/prefix for notebook inputs, outputs, and status files.
An IAM user or role for the local MCP server.
An EC2 instance role/profile for temporary notebook instances.
A default VPC/subnet or explicit subnet id.
SSM access; no inbound SSH is required.
The tested setup used:
AWS region: eu-north-1
S3 root: s3://YOUR_BUCKET/runs
EC2 instance profile: EC2NotebookRunnerRole
Instance type: t3.microIAM: Local MCP User
Attach a managed policy to the IAM principal used by your local AWS profile. Keep it scoped to your account and bucket where possible.
Minimal EC2/SSM/S3 policy shape:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PassNotebookRunnerRole",
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::123456789012:role/EC2NotebookRunnerRole"
},
{
"Sid": "EC2NotebookRunnerControl",
"Effect": "Allow",
"Action": [
"ec2:RunInstances",
"ec2:TerminateInstances",
"ec2:CreateTags",
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus",
"ec2:DescribeImages",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DescribeSecurityGroups"
],
"Resource": "*"
},
{
"Sid": "SSMNotebookRunnerControl",
"Effect": "Allow",
"Action": [
"ssm:SendCommand",
"ssm:GetCommandInvocation",
"ssm:DescribeInstanceInformation"
],
"Resource": "*"
},
{
"Sid": "NotebookRunnerS3Access",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::YOUR_BUCKET",
"arn:aws:s3:::YOUR_BUCKET/runs/*"
]
},
{
"Sid": "OptionalCloudWatchMetrics",
"Effect": "Allow",
"Action": "cloudwatch:GetMetricStatistics",
"Resource": "*"
}
]
}cloudwatch:GetMetricStatistics is optional. Without it, status still works,
but CPU/network/disk I/O metrics are reported as unavailable.
IAM: EC2 Instance Role
Create an EC2 role, for example EC2NotebookRunnerRole, with:
Trust policy for
ec2.amazonaws.com.AWS managed policy:
AmazonSSMManagedInstanceCore.S3 access to the run prefix.
Example inline S3 policy for the EC2 role:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "NotebookRunnerInstanceS3Access",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET/runs/ec2/*"
}
]
}When you create the role through the AWS console, AWS usually creates an instance profile with the same name as the role.
Environment
Core settings:
export AWS_PROFILE=research
export AWS_REGION=eu-north-1
export AWS_NOTEBOOK_RUNNER_ROOT=/absolute/path/to/local/notebooks
export AWS_NOTEBOOK_S3_ROOT=s3://YOUR_BUCKET/runs
export AWS_NOTEBOOK_BACKEND=ec2_ssm
export AWS_NOTEBOOK_ROLE_ARN=arn:aws:iam::123456789012:role/EC2NotebookRunnerRole
export AWS_NOTEBOOK_ALLOWED_INSTANCE_TYPES=t3.micro,t3.small
export AWS_NOTEBOOK_DEFAULT_INSTANCE_TYPE=t3.micro
export AWS_NOTEBOOK_MAX_RUNTIME_SECONDS=1800
export AWS_NOTEBOOK_MAX_ESTIMATED_COST_USD=1Paid compute is disabled unless you opt in:
export AWS_NOTEBOOK_RUNNER_ENABLE_EXECUTION=trueThe MCP caller must also pass:
confirmation_token = START_PAID_EC2_NOTEBOOK_RUNSageMaker execution, when quotas are available, uses:
confirmation_token = START_PAID_SAGEMAKER_NOTEBOOK_JOBMCP Client Configuration
Example stdio config:
{
"mcpServers": {
"aws-notebook-runner": {
"command": "aws-notebook-runner-mcp",
"env": {
"AWS_PROFILE": "research",
"AWS_REGION": "eu-north-1",
"AWS_NOTEBOOK_RUNNER_ROOT": "/absolute/path/to/notebooks",
"AWS_NOTEBOOK_S3_ROOT": "s3://YOUR_BUCKET/runs",
"AWS_NOTEBOOK_BACKEND": "ec2_ssm",
"AWS_NOTEBOOK_ROLE_ARN": "arn:aws:iam::123456789012:role/EC2NotebookRunnerRole",
"AWS_NOTEBOOK_ALLOWED_INSTANCE_TYPES": "t3.micro,t3.small",
"AWS_NOTEBOOK_DEFAULT_INSTANCE_TYPE": "t3.micro",
"AWS_NOTEBOOK_MAX_RUNTIME_SECONDS": "1800",
"AWS_NOTEBOOK_MAX_ESTIMATED_COST_USD": "1"
}
}
}
}Only add AWS_NOTEBOOK_RUNNER_ENABLE_EXECUTION=true when you are ready to allow
paid compute, and keep the confirmation token gate.
Tools
get_runner_status: local policy and dependency status.inspect_notebook: validate and summarize a local notebook.estimate_notebook_job_cost: estimate SageMaker or EC2 compute cost.plan_notebook_job: dry-run SageMaker plan.get_sagemaker_notebook_job_spec: return a SageMakerNotebookJobStepspec.start_sagemaker_notebook_job: guarded SageMaker execution.get_sagemaker_job_status: read SageMaker pipeline execution status.check_ec2_setup: read-only EC2/SSM readiness checks.plan_ec2_smoke_run: dry-run EC2+SSM plan.start_ec2_smoke_run: guarded synchronous EC2+SSM run.start_ec2_smoke_run_async: guarded async EC2+SSM run.get_ec2_smoke_run_status: EC2/SSM/S3 progress, metrics, artifacts, and cost.explain_existing_aws_options: related AWS options and overlap.
Typical EC2 Workflow
Inspect the notebook:
inspect_notebook(local_path="notebooks/demo.ipynb")Build a dry-run plan:
plan_ec2_smoke_run(
local_path="notebooks/demo.ipynb",
run_name="demo-run",
instance_type="t3.micro",
max_runtime_seconds=900,
instance_profile_name="EC2NotebookRunnerRole"
)Start async execution:
start_ec2_smoke_run_async(
local_path="notebooks/demo.ipynb",
run_name="demo-run",
confirmation_token="START_PAID_EC2_NOTEBOOK_RUN",
instance_type="t3.micro",
max_runtime_seconds=900,
instance_profile_name="EC2NotebookRunnerRole"
)Poll status:
get_ec2_smoke_run_status(run_name="demo-run")Status includes:
progress_summary.summary, for example:70% executing; elapsed wall 4m 44s, compute 4m 42s, ETA 2m 0sEC2 instance state.
SSM command status.
stdout/stderr tail.
S3 artifacts.
Current compute cost estimate.
Progress Model
Progress is phase-based:
created -> staged -> launching -> waiting_ssm -> installing -> executing -> uploading -> completed/failedThis is useful for UX and cost guardrails, but it is not exact cell-level
progress. A notebook that sleeps for five minutes will remain in executing
until it completes unless the notebook itself writes progress markers.
Cost Model
Cost reporting is an estimate:
EC2 compute is estimated from instance type, elapsed compute time, and a 60-second minimum.
EBS, S3 requests/storage, data transfer, and taxes are not included.
Static prices can be overridden:
export AWS_NOTEBOOK_PRICE_OVERRIDES_JSON='{"t3.micro": 0.0104, "ml.m5.large": 0.115}'Always verify official costs in AWS Billing or Cost Explorer.
SageMaker Notes
SageMaker Notebook Jobs are the more managed AWS-native way to run notebooks, but new AWS accounts may have a default training-job quota of zero for common instance types. In that case, EC2+SSM is a practical fallback.
The SageMaker backend is included, but EC2+SSM is the path that has been tested end-to-end in this package.
Troubleshooting
iam:PassRole denied:
The local AWS principal needs permission to pass the EC2 instance role:
iam:PassRole on arn:aws:iam::<account-id>:role/EC2NotebookRunnerRoleSSM command never starts:
Check that the instance role has
AmazonSSMManagedInstanceCore.Use an Amazon Linux AMI with SSM Agent.
Ensure the subnet has outbound internet access or VPC endpoints for SSM.
CloudWatch metrics unavailable:
Add cloudwatch:GetMetricStatistics to the local AWS principal.
SageMaker fails with quota zero:
Request quota for the selected instance type, or use the EC2+SSM backend.
Inline IAM policy size exceeded:
Use customer managed policies attached to the user/role instead of adding more inline policies.
Safety
This server is intentionally conservative:
Dry-run tools do not start compute.
Execution requires
AWS_NOTEBOOK_RUNNER_ENABLE_EXECUTION=true.Execution also requires a confirmation token.
Instance types are allowlisted.
Max runtime and max estimated cost are policy-controlled.
EC2 instances are launched with instance-initiated shutdown behavior set to terminate.
Review IAM, S3 prefixes, instance allowlists, and cost caps before enabling execution.
Available Tools
13 toolscheck_ec2_setupA
Read-only EC2/SSM setup checks; does not launch instances.
Inputs: no named parameters. Returns: object
estimate_notebook_job_costC
Estimate SageMaker notebook job compute cost from static or configured prices.
Inputs: instance_type, max_runtime_seconds. Returns: object
explain_existing_aws_optionsA
Explain related AWS/AWS Labs tools and how this prototype differs.
Inputs: no named parameters. Returns: object
get_ec2_smoke_run_statusC
Return EC2/SSM/S3 progress, CloudWatch metrics, and current cost estimate.
Inputs: run_name (required), include_cloudwatch, terminate_if_finished. Returns: object
get_runner_statusA
Return local policy and dependency status without contacting AWS.
Inputs: no named parameters. Returns: object
get_sagemaker_job_statusC
Read SageMaker pipeline execution status for a started notebook job.
Inputs: pipeline_execution_arn (required). Returns: object
get_sagemaker_notebook_job_specC
Return the SageMaker NotebookJobStep spec for a dry-run plan.
Inputs: local_path (required), job_name (required), image_uri (required), kernel_name, +3 more. Returns: object
inspect_notebookC
Inspect a local notebook under AWS_NOTEBOOK_RUNNER_ROOT.
Inputs: local_path (required). Returns: object
plan_ec2_smoke_runA
Build a dry-run EC2+SSM notebook smoke-run plan; does not launch EC2.
Inputs: local_path (required), run_name (required), instance_type, max_runtime_seconds, +4 more. Returns: object
plan_notebook_jobC
Build a dry-run SageMaker notebook job plan; does not start AWS compute.
Inputs: local_path (required), job_name (required), image_uri (required), kernel_name, +4 more. Returns: object
start_ec2_smoke_runC
Start a guarded paid EC2+SSM smoke run and terminate the instance after completion.
Inputs: local_path (required), run_name (required), confirmation_token (required), instance_type, +5 more. Returns: object
start_ec2_smoke_run_asyncC
Start a guarded paid EC2+SSM smoke run and return immediately with run ids.
Inputs: local_path (required), run_name (required), confirmation_token (required), instance_type, +5 more. Returns: object
start_sagemaker_notebook_jobC
Start paid SageMaker notebook execution only when policy and token allow it.
Inputs: local_path (required), job_name (required), image_uri (required), confirmation_token (required), +4 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct action (plan, start, check status, inspect, estimate) for separate AWS execution paths (EC2+SSM vs SageMaker), with clear descriptions that prevent confusion even between start_ec2_smoke_run and start_ec2_smoke_run_async.
All tool names follow a verb_noun pattern in snake_case consistently, using action verbs like check, estimate, explain, get, inspect, plan, start. No mixed conventions.
13 tools cover the full workflow for two execution modes without bloat. Each tool serves a clear purpose in the lifecycle (plan, start, status, cost, setup, inspection).
The tool set covers setup checks, planning, starting (sync and async for EC2), status retrieval, cost estimation, and notebook inspection. Missing a cancel/abort tool for running jobs, but the guarded design mitigates this gap.
Maintenance
Related MCP Connectors
Lowers your AWS bill by helping you clean up and optimize your setup
Create AWS cost estimates and shareable AWS Pricing Calculator URLs.
Lease AWS and GCP VMs for a set time and let them stop themselves.
AWS pricing and cost estimates with no signup, plus read-only idle-resource scans of your account.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables LLMs to create, destroy, and manage AWS EC2 instances, including running commands via interactive shells.1-
- FlicenseNot gradedqualityBmaintenanceEnables querying AWS cost and usage data, monitoring budgets, and auditing for waste such as stopped EC2 instances, unattached EBS volumes, and unassociated Elastic IPs through natural language across multiple AWS profiles and regions. Runs locally using existing AWS CLI credentials to keep them secure.-
- FlicenseNot gradedqualityAmaintenanceEnables users to query AWS cost and usage data, audit for wasted resources like stopped EC2 instances and unattached EBS volumes, and monitor budgets across multiple accounts and regions using natural language. Runs locally against existing AWS CLI profiles so credentials never leave the machine.-
- FlicenseNot gradedqualityAmaintenanceEnables users to query AWS cost and usage data, run waste and savings audits, monitor budgets, and compare multiple accounts or regions through natural-language prompts while keeping credentials local.-