@heimdall-ai/heimdall
Advanced tools
Heimdall - MCP server providing sandboxed Python and Bash execution
A TypeScript MCP server providing sandboxed Python and Bash execution using Pyodide (Python compiled to WebAssembly) and just-bash.
Named after the Norse god who guards the Bifröst bridge, Heimdall watches over code execution with security and vigilance.
┌──────────────────────────────────────────────────────────┐
│ MCP Client (Cursor) │
└────────────────────┬─────────────────────────────────────┘
│ MCP Protocol (stdio)
┌────────────────────▼─────────────────────────────────────┐
│ TypeScript MCP Server (Node.js) │
│ • @modelcontextprotocol/sdk │
│ • PyodideManager + BashManager │
│ • Virtual FS ↔ Host FS sync │
├──────────────────────┬──────────────────┬────────────────┤
│ Pyodide (WASM) │ just-bash (TS) │ Shared FS │
│ • Python runtime │ • Bash simulator│ • ./workspace │
│ • /workspace mount │ • 50+ commands │ • Persistence │
└──────────────────────┴──────────────────┴────────────────┘
npm install
npm run dev
npm run build
npm start
Add to your Cursor settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):
{
"mcpServers": {
"heimdall": {
"command": "node",
"args": ["dist/server.js"],
"cwd": "/path/to/heimdall"
}
}
}
Or for development with tsx:
{
"mcpServers": {
"heimdall": {
"command": "npx",
"args": ["tsx", "src/server.ts"],
"cwd": "/path/to/heimdall"
}
}
}
execute_bashExecute bash commands in the Heimdall environment using just-bash.
Features:
|, >, >>, 2>, 2>&1Security:
// Input
{
command: string; // Bash command to execute
cwd?: string; // Working directory (relative to /workspace)
}
// Output
{
stdout: string;
stderr: string;
exitCode: number;
}
Examples:
# Find Python files
find . -name "*.py" -type f
# Process text files
cat data.txt | grep "pattern" | wc -l
# JSON processing
cat data.json | jq '.users[] | {name, email}'
# Multiple commands
ls -la && cat README.md | head -10
# Text processing pipeline
grep -r "TODO" src/ | sort | uniq
execute_pythonExecute Python code in the sandbox. Packages are auto-detected from imports.
Note: Network access is NOT available - Pyodide runs in WebAssembly which provides a security boundary that prevents network requests.
// Input
{
code: string; // Python code to execute
packages?: string[]; // Optional additional packages (auto-detection handles most cases)
}
// Output
{
success: boolean;
stdout: string;
stderr: string;
result: string | null; // Last expression value
error: string | null;
}
Example:
# Packages are auto-detected - no need to specify numpy/pandas!
import numpy as np
import pandas as pd
data = np.array([1, 2, 3, 4, 5])
df = pd.DataFrame({'values': data, 'squared': data ** 2})
print(df)
install_packagesInstall Python packages via micropip.
// Input
{
packages: string[]; // Package names to install
}
// Output
{
results: Array<{
package: string;
success: boolean;
error: string | null;
}>;
}
write_fileWrite content to a file in the workspace.
// Input
{
path: string; // File path relative to workspace
content: string; // Content to write
}
read_fileRead a file from the workspace.
// Input
{
path: string; // File path relative to workspace
}
list_filesList files in a directory.
// Input
{
path?: string; // Directory path (empty for root)
}
// Output
{
files: Array<{
name: string;
isDirectory: boolean;
size: number;
}>;
}
delete_fileDelete a file or empty directory.
// Input
{
path: string; // File or directory path
}
| URI | Description |
|---|---|
workspace://files | Tree listing of workspace contents |
workspace://file/{path} | Read a specific file |
heimdall://info | Environment information |
Files are stored in the workspace/ directory.
Customize the server behavior with environment variables:
{
"mcpServers": {
"heimdall": {
"command": "node",
"args": ["dist/server.js"],
"cwd": "/path/to/heimdall",
"env": {
"HEIMDALL_WORKSPACE": "/custom/workspace/path",
"HEIMDALL_MAX_FILE_SIZE": "52428800",
"HEIMDALL_MAX_WORKSPACE_SIZE": "524288000",
"HEIMDALL_PYTHON_EXECUTION_TIMEOUT_MS": "5000"
}
}
}
}
Available environment variables:
| Variable | Description | Default | Format |
|---|---|---|---|
HEIMDALL_WORKSPACE | Path to workspace directory | ./workspace | Absolute or relative path |
HEIMDALL_MAX_FILE_SIZE | Maximum size for a single file | 10485760 (10MB) | Bytes (positive integer) |
HEIMDALL_MAX_WORKSPACE_SIZE | Maximum total workspace size | 104857600 (100MB) | Bytes (positive integer) |
HEIMDALL_PYTHON_EXECUTION_TIMEOUT_MS | Python execution timeout | 5000 | Milliseconds (positive integer) |
Example: To allow 50MB files and 500MB total workspace:
HEIMDALL_MAX_FILE_SIZE: 52428800 (50 * 1024 * 1024)HEIMDALL_MAX_WORKSPACE_SIZE: 524288000 (500 * 1024 * 1024)Python code cannot make network requests. Pyodide runs in WebAssembly which provides a security boundary that prevents:
This is enforced by the WASM runtime itself. Code that attempts to make network requests will fail with an error.
Package installation (micropip.install()) works because it uses Pyodide's internal mechanism which operates at the JavaScript/Node.js layer, not Python:
micropip.install("numpy") → Pyodide (JS) → Node.js fetch() → PyPI
This is intentional - packages can be installed via Pyodide's trusted mechanism, but user code cannot make arbitrary network requests.
| ✅ Available | ❌ Blocked |
|---|---|
| Package installation (micropip) | urllib.request.urlopen() |
| File I/O (workspace) | requests.get() |
| Data processing (numpy, pandas) | Socket connections |
URL parsing (urllib.parse) | External API calls |
loadPackagesFromImports() | Data exfiltration |
Pyodide includes many popular packages:
install_packagesSee Pyodide Packages for full compatibility list.
heimdall/
├── src/
│ ├── server.ts # Entry point
│ ├── config/
│ │ └── constants.ts # Configuration and limits
│ ├── core/
│ │ ├── bash-manager.ts # Bash execution (just-bash)
│ │ ├── pyodide-manager.ts # Python execution coordinator
│ │ ├── pyodide-worker.ts # Worker thread for Python
│ │ └── secure-fs.ts # Secure filesystem wrapper
│ ├── tools/
│ │ ├── bash-execution.ts # execute_bash tool
│ │ ├── python-execution.ts # execute_python tool
│ │ └── filesystem.ts # File operation tools
│ ├── resources/ # MCP resource handlers
│ ├── types/ # TypeScript interfaces
│ └── utils/ # Utilities (async-lock, etc.)
├── test/ # Vitest tests
├── dist/ # Compiled output
└── workspace/ # Persistent file storage
npm run build
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # With coverage
npm run validate # Type-check + lint + format + build
npm run clean
Bash and Python share the same workspace filesystem, enabling powerful workflows:
Example: Bash prepares data, Python analyzes
# Bash: Extract and clean data
cat raw_data.csv | grep -v '^#' | sort > clean_data.csv
# Python: Analyze the cleaned data
import pandas as pd
df = pd.read_csv('/workspace/clean_data.csv')
print(df.describe())
Example: Python generates data, Bash processes
# Python: Generate report data
import json
data = [{"name": "Alice", "score": 95}, {"name": "Bob", "score": 87}]
with open('/workspace/results.json', 'w') as f:
json.dump(data, f)
# Bash: Extract specific fields
cat results.json | jq '.[] | select(.score > 90) | .name'
Pyodide downloads ~15MB on first run. Subsequent runs use cached files.
Some packages aren't available in Pyodide. Check compatibility at pyodide.org.
WebAssembly has memory limits. For large datasets, process in chunks. You can increase Node.js heap with:
NODE_OPTIONS="--max-old-space-size=4096" npm start
MIT
FAQs
Heimdall - MCP server providing sandboxed Python and Bash execution
We found that @heimdall-ai/heimdall demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
On Front Lines’ Early Adopters: CISO podcast, Andrew Becherer shares lessons from Datadog, weighs the long-term costs of AI-built tools, and explains how founders can actually gain a CISO’s trust.
Security News
/Product
Socket for Origin scans dependency changes in pull requests and flags security risks based on your team’s policies. Now available in Cursor’s App Marketplace.
Security News
Agent Baseline’s new reference architecture shows how to secure software factories with four boundaries enforced outside the AI agent.