Connect AI assistants to local AWS with MCP

What Goku's MCP server does

The Model Context Protocol (MCP) is how AI assistants call tools. Goku serves it at http://localhost:8080/mcp, on the console's port, over Streamable HTTP, with 25 tools: Goku's own, and aws_call, which calls any operation of the emulated AWS services.

An assistant holding your AWS credentials can run up costs or delete something real. With Goku it works on a sandbox instead:

• No AWS account or keys. Every tool acts on the Goku on your machine.
• Mistakes are cheap. Save a snapshot first and restore it if the assistant goes too far.
• One local cloud. What the assistant creates, your AWS CLI, SDKs and the console see too.

Install Goku and the goku CLI

goku CLI 0.5.0 adds goku mcp, the bridge most clients start. On macOS and Linux:

$ curl -fsSL https://tanuj24.github.io/goku/install.sh | sh

On Windows, in PowerShell:

PS> irm https://tanuj24.github.io/goku/install.ps1 | iex

Already installed? Run goku update --cli and goku update: the MCP server needs Goku 4.1 or later. More options are on the install page.

Connect your assistant

Clients that start a command run goku mcp, which bridges stdio to the endpoint and starts Goku if it isn't running. Clients that take a URL connect to http://localhost:8080/mcp; nothing starts Goku over HTTP, so run goku start first.

Claude Code

$ claude mcp add goku -- goku mcp

Add --scope user for every project. Or over HTTP:

$ claude mcp add --transport http goku http://localhost:8080/mcp

To share it with your team, commit a .mcp.json:

{
  "mcpServers": {
    "goku": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}

Claude Desktop

Add Goku to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop:

{
  "mcpServers": {
    "goku": { "command": "goku", "args": ["mcp"] }
  }
}

Desktop apps don't see your shell's PATH: goku mcp config claude-desktop prints this entry with the full path of goku.

Cursor

In ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "goku": { "url": "http://localhost:8080/mcp" }
  }
}

With the goku CLI instead: { "command": "goku", "args": ["mcp"] }.

VS Code

In .vscode/mcp.json:

{
  "servers": {
    "goku": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}

With the goku CLI instead: { "type": "stdio", "command": "goku", "args": ["mcp"] }.

Windsurf and every other client

goku mcp config prints each client's setup and the file it goes in:

$ goku mcp config          # Claude Code, Claude Desktop, Cursor, VS Code and Windsurf
goku mcp config windsurf   # or claude-code, claude-desktop, cursor, vscode

Windsurf's file is ~/.codeium/windsurf/mcp_config.json. Other clients take the URL (Streamable HTTP) or goku mcp (stdio). The console's MCP page, http://localhost:8080/ai-assistants, shows the same setup.

Ask for what you need

Ask in plain language. From the console's Things to ask:

• Create a DynamoDB table called orders and add three sample orders to it.
• Deploy a Python Lambda function that says hello, invoke it, and show me its logs.
• My order-processor Lambda fails. Find out why from its logs and the recent request journeys.
• Throttle half of the DynamoDB PutItem calls for five minutes, so I can test my retries.
• Save a snapshot called before-migration, then run the migration script.
• Can the role LambdaExecutionRole read from the S3 bucket reports?

The 25 tools

Goku's tools start with goku_; the AWS tools reach every emulated service.

Tool hints such as readOnlyHint and destructiveHint let clients that confirm destructive actions ask before aws_call, goku_service_delete, goku_snapshot_restore, goku_snapshot_reset, goku_chaos_remove and goku_chaos_clear.

How aws_call works

aws_call sends any operation of an emulated service with the AWS SDK for JavaScript v3. The assistant passes the service, operation and input as JSON:

{
  "service": "dynamodb",
  "operation": "PutItem",
  "input": {
    "TableName": "orders",
    "Item": { "id": { "S": "o-1" }, "total": { "N": "42" } }
  }
}

• service takes the API name (dynamodb, stepfunctions), the SDK client name (sfn) or an alias (states, eventbridge); operation takes PutItem, putItem or put-item.
• Binary data goes in as base64, as with the AWS CLI, and comes back as text when it is UTF-8, base64 otherwise, up to 1 MB.
• AWS errors come back as a tool error with the error name, message and HTTP status.
• account_id and region act in another Goku account or region.

Security, and turning it off

The endpoint gives full access to your local Goku without a confirmation step, so it only answers requests from your machine:

• Answers only this machine's names: localhost, 127.0.0.1, [::1], host.docker.internal, *.localhost and names Goku is configured with. This blocks DNS rebinding.
• Refuses other websites: browser requests from any origin but the Goku console get 403. Command-line and desktop clients, which send no Origin, are allowed.

Settings, on the Goku container:

• GOKU_MCP=off turns the endpoint off: /mcp answers 404. The default is on.
• GOKU_MCP_ALLOWED_HOSTS: more host names the endpoint answers to, comma-separated.
• GOKU_MCP_ALLOWED_ORIGINS: more browser origins allowed to call it, comma-separated.

For example, docker run -e GOKU_MCP=off … starts Goku without it. goku doctor says whether the endpoint answers.

More Goku guides