@aws/run-mcp-servers-with-aws-lambda

Run Model Context Protocol (MCP) servers with AWS Lambda

This project enables you to run Model Context Protocol stdio-based servers in AWS Lambda functions.

Currently, most implementations of MCP servers and clients are entirely local on a single machine. A desktop application such as an IDE or Claude Desktop initiates MCP servers locally as child processes and communicates with each of those servers over a long-running stdio stream.

flowchart LR
    subgraph "Your Laptop"
        Host["Desktop Application<br>with MCP Clients"]
        S1["MCP Server A<br>(child process)"]
        S2["MCP Server B<br>(child process)"]
        Host <-->|"MCP Protocol<br>(over stdio stream)"| S1
        Host <-->|"MCP Protocol<br>(over stdio stream)"| S2
    end

This MCP server adapter for AWS Lambda helps you to wrap existing stdio MCP servers into Lambda functions. You can invoke these function-based MCP servers from your application using the MCP protocol over short-lived connections. Your application can then be a desktop-based app, a distributed system running in the cloud, or any other architecture. Your application must have access to invoke your Lambda functions, and use the custom MCP client transport that invokes the Lambda functions.

flowchart LR
    subgraph "Distributed System"
        App["Your Application<br>with MCP Clients"]
        S3["MCP Server A<br>(Lambda function)"]
        S4["MCP Server B<br>(Lambda function)"]
        App <-->|"MCP Protocol<br>with custom transport<br>(invoke function)"| S3
        App <-->|"MCP Protocol<br>with custom transport<br>(invoke function)"| S4
    end

Considerations

• If you are looking for a way to invoke existing Lambda functions as tools through MCP, see the AWS Lambda MCP Server project.
• This package currently requires using a custom MCP client transport to communicate with the MCP server by invoking the Lambda function. Existing applications with MCP support such as Amazon Q Developer CLI, Cline, etc do not have this custom transport, and cannot communicate with MCP servers adapted into Lambda functions. Note: with upcoming changes to the MCP protocol, we expect that this limitation will be removed in the future.
• This package currently supports MCP servers and clients written in Python and Typescript. Other languages such as Kotlin are not supported.
• The server adapters only adapt stdio MCP servers, not servers written for other protocols such as SSE.
• The server adapters do not maintain any MCP server state across Lambda function invocations. Only stateless MCP servers are a good fit for using this adapter. For example, MCP servers that invoke stateless tools like the time MCP server or make stateless web requests like the fetch MCP server. Stateful MCP servers are not a good fit, because they will lose their state on every request. For example, MCP servers that manage data on disk or in memory such as the sqlite MCP server, the filesystem MCP server, and the git MCP server.
• The server adapters ignore any MCP protocol notifications from the client to the server.
• The server adapters do not provide mechanisms for managing any secrets needed by the wrapped MCP server. For example, the GitHub MCP server and the Brave search MCP server require API keys to make requests to third-party APIs. You can configure these API keys as encrypted environment variables in the Lambda function's configuration. However, note that anyone with access to invoke the Lambda function will then have access to use your API key to call the third-party APIs by invoking the function. We recommend limiting access to the Lambda function using least-privilege IAM policies.

Examples

Python server example

This project includes an example Python Lambda function that runs the simple MCP 'time' reference server. The Lambda function bundles the mcp-server-time package. On each function invocation, the Lambda function will manage the lifecycle of the bundled MCP server. It will:

1. start the 'time' MCP server as a child process
2. initialize the MCP server
3. forward the incoming request to the local server
4. return the server's response to the function caller
5. shut down the MCP server child process

import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import stdio_server_adapter

server_params = StdioServerParameters(
    command=sys.executable,
    args=[
        "-m",
        "mcp_server_time",
        "--local-timezone",
        "America/New_York",
    ],
)


def handler(event, context):
    return stdio_server_adapter(server_params, event, context)

Typescript server example

This project includes an example Node.js Lambda function that runs an OpenAPI MCP server to provide a single API from weather.gov as a tool. The Lambda function bundles the openapi-mcp-server package. On each function invocation, the Lambda function will manage the lifecycle of the bundled MCP server. It will:

1. start the 'openapi-mcp-server' MCP server as a child process
2. initialize the MCP server
3. forward the incoming request to the local server
4. return the server's response to the function caller
5. shut down the MCP server child process

import { Handler, Context } from "aws-lambda";

const serverParams = {
  command: "npx",
  args: ["--offline", "openapi-mcp-server", "./weather-alerts-openapi.json"],
};

export const handler: Handler = async (event, context: Context) => {
  // Dynamically import ES module into CommonJS Lambda function
  const { stdioServerAdapter } = await import(
    "@aws/run-mcp-servers-with-aws-lambda"
  );

  return await stdioServerAdapter(serverParams, event, context);
};

Python client example

This project includes an example Python MCP client that invokes the 'time' MCP server function from above. The client invokes a Lambda function named "mcp-server-time" with a payload that is compliant with the MCP protocol and returns the function's response to the caller.

from mcp import ClientSession
from mcp_lambda import LambdaFunctionParameters, lambda_function_client

server_params = LambdaFunctionParameters(
    function_name="mcp-server-time",
    region_name="us-east-2",
)

read, write = await lambda_function_client(server_params)
session = ClientSession(read, write)
await session.initialize()

Typescript client example

This project includes an example Typescript MCP client that invokes the 'time' MCP server function from above. The client invokes a Lambda function named "mcp-server-time" with a payload that is compliant with the MCP protocol and returns the function's response to the caller.

import {
  LambdaFunctionParameters,
  LambdaFunctionClientTransport,
} from "@aws/run-mcp-servers-with-aws-lambda";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const serverParams: LambdaFunctionParameters = {
  functionName: "mcp-server-time",
  regionName: "us-east-2",
};

const client = new Client(
  {
    name: "my-client",
    version: "0.0.1",
  },
  {
    capabilities: {
      sampling: {},
    },
  }
);

const transport = new LambdaFunctionClientTransport(serverParams);
await client.connect(transport);

Deploy and run the examples

See the development guide for instructions to deploy and run the examples in this repository.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.