What is Run Model Context Protocol Servers With Aws Lambda

run-model-context-protocol-servers-with-aws-lambda is a project that allows you to run existing Model Context Protocol (MCP) stdio-based servers within AWS Lambda functions, enabling cloud-based execution of these servers.

Use cases

Use cases include running MCP servers for cloud-based applications, integrating MCP functionality into distributed systems, and enabling remote access to MCP servers from desktop applications.

How to use

To use this project, you need to wrap your existing stdio MCP servers into Lambda functions. You can then invoke these functions from your application using a custom MCP client transport that communicates with the Lambda functions over short-lived connections.

Key features

Key features include the ability to run MCP servers in a serverless environment, integration with AWS Lambda, and the use of custom transport for invoking functions, which allows for flexible application architectures.

Where to use

This project is suitable for various fields, including cloud computing, distributed systems, and applications that require remote execution of MCP servers, such as IDEs and other desktop applications.

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.