run-model-context-protocol-servers-with-aws-lambda

# Run Model Context Protocol (MCP) servers with AWS Lambda [](https://pypi.org/project/run-mcp-servers-with-aws-lambda/) [](https://www.npmjs.com/package/@aws/run-mcp-servers-with-aws-lambda) This project enables you to run [Model Context Protocol](https://modelcontextprotocol.io) 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. ```mermaid 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 library 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 HTTPS connections. Your application can then be a desktop-based app, a distributed system running in the cloud, or any other architecture. ```mermaid 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>(over HTTPS connection)"| S3 App <-->|"MCP Protocol<br>(over HTTPS connection)"| S4 end ``` Using this library, the Lambda function will manage the lifecycle of your stdio MCP server. Each Lambda function invocation will: 1. Start the stdio MCP server as a child process 1. Initialize the MCP server 1. Forward the incoming request to the local server 1. Return the server's response to the function caller 1. Shut down the MCP server child process This library supports connecting to Lambda-based MCP servers in four ways: 1. The [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http), using Amazon API Gateway. Typically authenticated using OAuth. 1. The MCP Streamable HTTP transport, using Amazon Bedrock AgentCore Gateway. Authenticated using OAuth. 1. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM. 1. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM. ## Determine your server parameters Many stdio-based MCP servers's documentation encourages using tools that download and run the server on-demand. For example, `uvx my-mcp-server` or `npx my-mcp-server`. These tools are often not pre-packaged in the Lambda environment, and it can be inefficient to re-download the server on every Lambda invocation. Instead, the examples in this repository show how to package the MCP server along with the Lambda function code, then start it with `python` or `node` (or `npx --offline`) directly. You will need to determine the right parameters depending on your MCP server's package. This can often be a trial and error process locally, since MCP server packaging varies. <details> <summary><b>Python server examples</b></summary> Basic example: ```python from mcp.client.stdio import StdioServerParameters server_params = StdioServerParameters( command=sys.executable, args=[ "-m", "my_mcp_server_python_module", "--my-server-command-line-parameter", "some_value", ], ) ``` Locally, you would run this module using: ```bash python -m my_mcp_server_python_module --my-server-command-line-parameter some_value ``` Other examples: ```bash python -m mcpdoc.cli # Note the sub-module python -c "from mcp_openapi_proxy import main; main()" python -c "import asyncio; from postgres_mcp.server import main; asyncio.run(main())" ``` If you use Lambda layers, you need to also set the PYTHONPATH for the python sub-process: ```python lambda_paths = ["/opt/python"] + sys.path env_config = {"PYTHONPATH": ":".join(lambda_paths)} server_params = StdioServerParameters( command=sys.executable, args=[ "-c", "from mcp_openapi_proxy import main; main()", ], env=env_config, ) ``` </details> <details> <summary><b>Typescript server examples</b></summary> Basic example: ```typescript const serverParams = { command: "npx", args: [ "--offline", "my-mcp-server-typescript-module", "--my-server-command-line-parameter", "some_value", ], }; ``` Locally, you would run this module using: ```bash npx --o