# Run Model Context Protocol (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 three 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.
2. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.
3. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM.
## Using API Gateway
```mermaid
flowchart LR
App["MCP Client"]
T1["MCP Server<br>(Lambda function)"]
T2["API Gateway"]
T3["OAuth Server<br>(Cognito or similar)"]
App -->|"MCP Streamable<br>HTTP Transport"| T2
T2 -->|"Invoke"| T1
T2 -->|"Authorize"| T3
```
This solution is compatible with most MCP clients that support the streamable HTTP transport.
MCP servers deployed with this architecture can typically be used with off-the-shelf
MCP-compatible applications such as Cursor, Cline, Claude Desktop, etc.
You can choose your desired OAuth server provider for this solution. The examples in this
repository use Amazon Cognito, or you can use third-party providers such as Okta or Auth0
with API Gateway custom authorization.
<details>
<summary><b>Python server example</b></summary>
```python
import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import APIGatewayProxyEventHandler, StdioServerAdapterRequestHandler
server_params = StdioServerParameters(
command=sys.executable,
args=[
"-m",
"my_mcp_server_python_module",
"--my-server-command-line-parameter",
"some_value",
],
)
request_handler = StdioServerAdapterRequestHandler(server_params)
event_handler = APIGatewayProxyEventHandler(request_handler)
def handler(event, context):
return event_handler.handle(event, context)
```
See a full, deployable example [here](examples/servers/dad-jokes/).
</details>
<details>
<summary><b>Typescript server example</b></summary>
```typescript
import {
Handler,
Context,
APIGatewayProxyWithCognitoAuthorizerEvent,
APIGatewayProxyResult,
} from "aws-lambda";
import {
APIGatewayProxyEventHandler,
StdioServerAdapterRequestHandler,
} from "@aws/run-mcp-servers-with-aws-lambda";
const serverParams = {
command: "npx",
args: [
"--offline",
"my-mcp-server-typescript-module",
"--my-server-command-line-parameter",
"some_value",
],
};
const requestHandler = new APIGatewayProxyEventHandler(
new StdioServerAdapterRequestHandler(serverParams)
);
export const handler: Handler = async (
event: APIGatewayProxyWithCognitoAuthorizerEvent,
context: Context
): Promise<APIGatewayProxyResult> => {
return requestHandler.handle(event, context);
};
```
See a full, deployable example [here](examples/servers/dog-facts/).
</details>
<details>
<summary><b>Python client example</b></summary>
```python
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
# Create OAuth client provider here
async with streamablehttp_client(
url="https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
auth=oauth_client_provider,
) as (
read_stream,
write_stream,
_,
):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tool_result = await session.call_tool("echo", {"message": "hello"})
```
See a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/interactive_oauth.py).
</details>
<details>
<summary><b>Typescript client example</b></summary>
```typescript
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const client = new Client(
{
name: "my-client",
version: "0.0.1",
},
{
capabilities: {
sampling: {},
},
}
);
// Create OAuth client provider here
const transport = new StreamableHTTPClientTransport(
"https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp",
{
authProvider: oauthProvider,
}
);
await client.connect(transport);
```
See a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/interactive_oauth.ts).
</details>
## Using a Lambda function URL
```mermaid
flowchart LR
App["MCP Client"]
T1["MCP Server<br>(Lambda function)"]
T2["Lambda function URL"]
App -->|"Custom Streamable HTTP<br>Transport with AWS Auth"| T2
T2 -->|"Invoke"| T1
```
This solution uses AWS IAM for authentication, and relies on granting
[Lambda InvokeFunctionUrl permission](https://docs.aws.amazon.com/lambda/latest/dg/urls-auth.html#urls-auth-iam) to your
IAM users and roles to enable access to the MCP server. Clients must use an extension to the MCP Streamable
HTTP transport that signs requests with [AWS SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).
Off-the-shelf MCP-compatible applications are unlikely to have support for this custom transport,
so this solution is more appropriate for service-to-service communication rather than for end users.
<details>
<summary><b>Python server example</b></summary>
```python
import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import LambdaFunctionURLEventHandler, StdioServerAdapterRequestHandler
server_params = StdioServerParameters(
command=sys.executable,
args=[
"-m",
"my_mcp_server_python_module",
"--my-server-command-line-parameter",
"some_value",
],
)
request_handler = StdioServerAdapterRequestHandler(server_params)
event_handler = LambdaFunctionURLEventHandler(request_handler)
def handler(event, context):
return event_handler.handle(event, context)
```
See a full, deployable example [here](examples/servers/mcpdoc/).
</details>
<details>
<summary><b>Typescript server example</b></summary>
```typescript
import {
Handler,
Context,
APIGatewayProxyEventV2WithIAMAuthorizer,
APIGatewayProxyResultV2,
} from "aws-lambda";
import {
LambdaFunctionURLEventHandler,
StdioServerAdapterRequestHandler,
} from "@aws/run-mcp-servers-with-aws-lambda";
const serverParams = {
command: "npx",
args: [
"--offline",
"my-mcp-server-typescript-module",
"--my-server-command-line-parameter",
"some_value",
],
};
const requestHandler = new LambdaFunctionURLEventHandler(
new StdioServerAdapterRequestHandler(serverParams)
);
export const handler: Handler = async (
event: APIGatewayProxyEventV2WithIAMAuthorizer,
context: Context
): Promise<APIGatewayProxyResultV2> => {
return requestHandler.handle(event, context);
};
```
See a full, deployable example [here](examples/servers/cat-facts/).
</details>
<details>
<summary><b>Python client example</b></summary>
```python
from mcp import ClientSession
from mcp_lambda.client.streamable_http_sigv4 import streamablehttp_client_with_sigv4
async with streamablehttp_client_with_sigv4(
url="https://url-id-12345.lambda-url.us-east-2.on.aws",
service="lambda",
region="us-east-2",
) as (
read_stream,
write_stream,
_,
):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tool_result = await session.call_tool("echo", {"message": "hello"})
```
See a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/lambda_function_url.py).
</details>
<details>
<summary><b>Typescript client example</b></summary>
```typescript
import { StreamableHTTPClientWithSigV4Transport } from "@aws/run-mcp-servers-with-aws-lambda";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const client = new Client(
{
name: "my-client",
version: "0.0.1",
},
{
capabilities: {
sampling: {},
},
}
);
const transport = new StreamableHTTPClientWithSigV4Transport(
new URL("https://url-id-12345.lambda-url.us-east-2.on.aws"),
{
service: "lambda",
region: "us-east-2",
}
);
await client.connect(transport);
```
See a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/lambda_function_url.ts).
</details>
## Using the Lambda Invoke API
```mermaid
flowchart LR
App["MCP Client"]
T1["MCP Server<br>(Lambda function)"]
App -->|"Custom MCP Transport<br>(Lambda Invoke API)"| T1
```
Like the Lambda function URL approach, this solution uses AWS IAM for authentication.
It relies on granting
[Lambda InvokeFunction permission](https://docs.aws.amazon.com/lambda/latest/dg/lambda-api-permissions-ref.html)
to your IAM users and roles to enable access to the MCP server.
Clients must use a custom MCP transport that directly calls the
[Lambda Invoke API](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html).
Off-the-shelf MCP-compatible applications are unlikely to have support for this custom transport,
so this solution is more appropriate for service-to-service communication rather than for end users.
<details>
<summary><b>Python server example</b></summary>
```python
import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import stdio_server_adapter
server_params = StdioServerParameters(
command=sys.executable,
args=[
"-m",
"my_mcp_server_python_module",
"--my-server-command-line-parameter",
"some_value",
],
)
def handler(event, context):
return stdio_server_adapter(server_params, event, context)
```
See a full, deployable example [here](examples/servers/time/).
</details>
<details>
<summary><b>Typescript server example</b></summary>
```typescript
import { Handler, Context } from "aws-lambda";
import { stdioServerAdapter } from "@aws/run-mcp-servers-with-aws-lambda";
const serverParams = {
command: "npx",
args: [
"--offline",
"my-mcp-server-typescript-module",
"--my-server-command-line-parameter",
"some_value",
],
};
export const handler: Handler = async (event, context: Context) => {
return await stdioServerAdapter(serverParams, event, context);
};
```
See a full, deployable example [here](examples/servers/weather-alerts/).
</details>
<details>
<summary><b>Python client example</b></summary>
```python
from mcp import ClientSession
from mcp_lambda import LambdaFunctionParameters, lambda_function_client
server_params = LambdaFunctionParameters(
function_name="my-mcp-server-function",
region_name="us-east-2",
)
async with lambda_function_client(server_params) as (
read_stream,
write_stream,
):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tool_result = await session.call_tool("echo", {"message": "hello"})
```
See a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/lambda_function.py).
</details>
<details>
<summary><b>Typescript client example</b></summary>
```typescript
import {
LambdaFunctionParameters,
LambdaFunctionClientTransport,
} from "@aws/run-mcp-servers-with-aws-lambda";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const serverParams: LambdaFunctionParameters = {
functionName: "my-mcp-server-function",
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);
```
See a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/lambda_function.ts).
</details>
## Related projects
- To write custom MCP servers in Lambda functions,
see the [MCP Lambda Handler](https://github.com/awslabs/mcp/tree/main/src/mcp-lambda-handler) project.
- To invoke existing Lambda functions as tools through a stdio MCP server,
see the [AWS Lambda Tool MCP Server](https://awslabs.github.io/mcp/servers/lambda-tool-mcp-server/) project.
## Considerations
- This library currently supports MCP servers and clients written in Python and Typescript.
Other languages such as Kotlin are not supported.
- This library only adapts stdio MCP servers for Lambda, not servers written for other protocols such as SSE.
- This library does not maintain any MCP server state or sessions 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](https://github.com/modelcontextprotocol/servers/tree/main/src/time)
or make stateless web requests like the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch).
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](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite),
the [filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem),
and the [git MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/git).
- This library does not provide mechanisms for managing any secrets needed by the wrapped
MCP server. For example, the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github)
and the [Brave search MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)
require API keys to make requests to third-party APIs.
You may configure these API keys as
[encrypted environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars-encryption.html)
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](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html).
If you use an identity-based authentication mechanism such as OAuth, you could also store and retrieve API keys per user but there are no implementation examples in this repository.
## Deploy and run the examples
See the [development guide](DEVELOP.md) for instructions to deploy and run the examples in this repository.
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
## License
This project is licensed under the Apache-2.0 License.
Raw data
{
"_id": null,
"home_page": null,
"name": "run-mcp-servers-with-aws-lambda",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "aws, lambda, mcp, modelcontextprotocol",
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a9/71/24f565b5b4a8de4b6b5667bd5870ac091a4dea70b3d8f5e9e85da161e852/run_mcp_servers_with_aws_lambda-0.3.3.tar.gz",
"platform": null,
"description": "# Run Model Context Protocol (MCP) servers with AWS Lambda\n\nThis project enables you to run [Model Context Protocol](https://modelcontextprotocol.io) stdio-based servers in AWS Lambda functions.\n\nCurrently, most implementations of MCP servers and clients are entirely local on a single machine.\nA desktop application such as an IDE or Claude Desktop initiates MCP servers locally as child processes\nand communicates with each of those servers over a long-running stdio stream.\n\n```mermaid\nflowchart LR\n subgraph \"Your Laptop\"\n Host[\"Desktop Application<br>with MCP Clients\"]\n S1[\"MCP Server A<br>(child process)\"]\n S2[\"MCP Server B<br>(child process)\"]\n Host <-->|\"MCP Protocol<br>(over stdio stream)\"| S1\n Host <-->|\"MCP Protocol<br>(over stdio stream)\"| S2\n end\n```\n\nThis library helps you to wrap existing stdio MCP servers into Lambda functions.\nYou can invoke these function-based MCP servers from your application using the MCP protocol\nover short-lived HTTPS connections.\nYour application can then be a desktop-based app, a distributed system running in the cloud,\nor any other architecture.\n\n```mermaid\nflowchart LR\n subgraph \"Distributed System\"\n App[\"Your Application<br>with MCP Clients\"]\n S3[\"MCP Server A<br>(Lambda function)\"]\n S4[\"MCP Server B<br>(Lambda function)\"]\n App <-->|\"MCP Protocol<br>(over HTTPS connection)\"| S3\n App <-->|\"MCP Protocol<br>(over HTTPS connection)\"| S4\n end\n```\n\nUsing this library, the Lambda function will manage the lifecycle of your stdio MCP server.\nEach Lambda function invocation will:\n\n1. Start the stdio MCP server as a child process\n1. Initialize the MCP server\n1. Forward the incoming request to the local server\n1. Return the server's response to the function caller\n1. Shut down the MCP server child process\n\nThis library supports connecting to Lambda-based MCP servers in three ways:\n\n1. The [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http), using Amazon API Gateway. Typically authenticated using OAuth.\n2. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.\n3. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM.\n\n## Using API Gateway\n\n```mermaid\nflowchart LR\n App[\"MCP Client\"]\n T1[\"MCP Server<br>(Lambda function)\"]\n T2[\"API Gateway\"]\n T3[\"OAuth Server<br>(Cognito or similar)\"]\n App -->|\"MCP Streamable<br>HTTP Transport\"| T2\n T2 -->|\"Invoke\"| T1\n T2 -->|\"Authorize\"| T3\n```\n\nThis solution is compatible with most MCP clients that support the streamable HTTP transport.\nMCP servers deployed with this architecture can typically be used with off-the-shelf\nMCP-compatible applications such as Cursor, Cline, Claude Desktop, etc.\n\nYou can choose your desired OAuth server provider for this solution. The examples in this\nrepository use Amazon Cognito, or you can use third-party providers such as Okta or Auth0\nwith API Gateway custom authorization.\n\n<details>\n\n<summary><b>Python server example</b></summary>\n\n```python\nimport sys\nfrom mcp.client.stdio import StdioServerParameters\nfrom mcp_lambda import APIGatewayProxyEventHandler, StdioServerAdapterRequestHandler\n\nserver_params = StdioServerParameters(\n command=sys.executable,\n args=[\n \"-m\",\n \"my_mcp_server_python_module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n)\n\n\nrequest_handler = StdioServerAdapterRequestHandler(server_params)\nevent_handler = APIGatewayProxyEventHandler(request_handler)\n\n\ndef handler(event, context):\n return event_handler.handle(event, context)\n```\n\nSee a full, deployable example [here](examples/servers/dad-jokes/).\n\n</details>\n\n<details>\n\n<summary><b>Typescript server example</b></summary>\n\n```typescript\nimport {\n Handler,\n Context,\n APIGatewayProxyWithCognitoAuthorizerEvent,\n APIGatewayProxyResult,\n} from \"aws-lambda\";\nimport {\n APIGatewayProxyEventHandler,\n StdioServerAdapterRequestHandler,\n} from \"@aws/run-mcp-servers-with-aws-lambda\";\n\nconst serverParams = {\n command: \"npx\",\n args: [\n \"--offline\",\n \"my-mcp-server-typescript-module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n};\n\nconst requestHandler = new APIGatewayProxyEventHandler(\n new StdioServerAdapterRequestHandler(serverParams)\n);\n\nexport const handler: Handler = async (\n event: APIGatewayProxyWithCognitoAuthorizerEvent,\n context: Context\n): Promise<APIGatewayProxyResult> => {\n return requestHandler.handle(event, context);\n};\n```\n\nSee a full, deployable example [here](examples/servers/dog-facts/).\n\n</details>\n\n<details>\n\n<summary><b>Python client example</b></summary>\n\n```python\nfrom mcp import ClientSession\nfrom mcp.client.streamable_http import streamablehttp_client\n\n# Create OAuth client provider here\n\nasync with streamablehttp_client(\n url=\"https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp\",\n auth=oauth_client_provider,\n) as (\n read_stream,\n write_stream,\n _,\n):\n async with ClientSession(read_stream, write_stream) as session:\n await session.initialize()\n tool_result = await session.call_tool(\"echo\", {\"message\": \"hello\"})\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/interactive_oauth.py).\n\n</details>\n\n<details>\n\n<summary><b>Typescript client example</b></summary>\n\n```typescript\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\n\nconst client = new Client(\n {\n name: \"my-client\",\n version: \"0.0.1\",\n },\n {\n capabilities: {\n sampling: {},\n },\n }\n);\n\n// Create OAuth client provider here\n\nconst transport = new StreamableHTTPClientTransport(\n \"https://abc123.execute-api.us-east-2.amazonaws.com/prod/mcp\",\n {\n authProvider: oauthProvider,\n }\n);\nawait client.connect(transport);\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/interactive_oauth.ts).\n\n</details>\n\n## Using a Lambda function URL\n\n```mermaid\nflowchart LR\n App[\"MCP Client\"]\n T1[\"MCP Server<br>(Lambda function)\"]\n T2[\"Lambda function URL\"]\n App -->|\"Custom Streamable HTTP<br>Transport with AWS Auth\"| T2\n T2 -->|\"Invoke\"| T1\n```\n\nThis solution uses AWS IAM for authentication, and relies on granting\n[Lambda InvokeFunctionUrl permission](https://docs.aws.amazon.com/lambda/latest/dg/urls-auth.html#urls-auth-iam) to your\nIAM users and roles to enable access to the MCP server. Clients must use an extension to the MCP Streamable\nHTTP transport that signs requests with [AWS SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).\nOff-the-shelf MCP-compatible applications are unlikely to have support for this custom transport,\nso this solution is more appropriate for service-to-service communication rather than for end users.\n\n<details>\n\n<summary><b>Python server example</b></summary>\n\n```python\nimport sys\nfrom mcp.client.stdio import StdioServerParameters\nfrom mcp_lambda import LambdaFunctionURLEventHandler, StdioServerAdapterRequestHandler\n\nserver_params = StdioServerParameters(\n command=sys.executable,\n args=[\n \"-m\",\n \"my_mcp_server_python_module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n)\n\n\nrequest_handler = StdioServerAdapterRequestHandler(server_params)\nevent_handler = LambdaFunctionURLEventHandler(request_handler)\n\n\ndef handler(event, context):\n return event_handler.handle(event, context)\n```\n\nSee a full, deployable example [here](examples/servers/mcpdoc/).\n\n</details>\n\n<details>\n\n<summary><b>Typescript server example</b></summary>\n\n```typescript\nimport {\n Handler,\n Context,\n APIGatewayProxyEventV2WithIAMAuthorizer,\n APIGatewayProxyResultV2,\n} from \"aws-lambda\";\nimport {\n LambdaFunctionURLEventHandler,\n StdioServerAdapterRequestHandler,\n} from \"@aws/run-mcp-servers-with-aws-lambda\";\n\nconst serverParams = {\n command: \"npx\",\n args: [\n \"--offline\",\n \"my-mcp-server-typescript-module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n};\n\nconst requestHandler = new LambdaFunctionURLEventHandler(\n new StdioServerAdapterRequestHandler(serverParams)\n);\n\nexport const handler: Handler = async (\n event: APIGatewayProxyEventV2WithIAMAuthorizer,\n context: Context\n): Promise<APIGatewayProxyResultV2> => {\n return requestHandler.handle(event, context);\n};\n```\n\nSee a full, deployable example [here](examples/servers/cat-facts/).\n\n</details>\n\n<details>\n\n<summary><b>Python client example</b></summary>\n\n```python\nfrom mcp import ClientSession\nfrom mcp_lambda.client.streamable_http_sigv4 import streamablehttp_client_with_sigv4\n\nasync with streamablehttp_client_with_sigv4(\n url=\"https://url-id-12345.lambda-url.us-east-2.on.aws\",\n service=\"lambda\",\n region=\"us-east-2\",\n) as (\n read_stream,\n write_stream,\n _,\n):\n async with ClientSession(read_stream, write_stream) as session:\n await session.initialize()\n tool_result = await session.call_tool(\"echo\", {\"message\": \"hello\"})\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/lambda_function_url.py).\n\n</details>\n\n<details>\n\n<summary><b>Typescript client example</b></summary>\n\n```typescript\nimport { StreamableHTTPClientWithSigV4Transport } from \"@aws/run-mcp-servers-with-aws-lambda\";\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\n\nconst client = new Client(\n {\n name: \"my-client\",\n version: \"0.0.1\",\n },\n {\n capabilities: {\n sampling: {},\n },\n }\n);\n\nconst transport = new StreamableHTTPClientWithSigV4Transport(\n new URL(\"https://url-id-12345.lambda-url.us-east-2.on.aws\"),\n {\n service: \"lambda\",\n region: \"us-east-2\",\n }\n);\nawait client.connect(transport);\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/lambda_function_url.ts).\n\n</details>\n\n## Using the Lambda Invoke API\n\n```mermaid\nflowchart LR\n App[\"MCP Client\"]\n T1[\"MCP Server<br>(Lambda function)\"]\n App -->|\"Custom MCP Transport<br>(Lambda Invoke API)\"| T1\n```\n\nLike the Lambda function URL approach, this solution uses AWS IAM for authentication.\nIt relies on granting\n[Lambda InvokeFunction permission](https://docs.aws.amazon.com/lambda/latest/dg/lambda-api-permissions-ref.html)\nto your IAM users and roles to enable access to the MCP server.\nClients must use a custom MCP transport that directly calls the\n[Lambda Invoke API](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html).\nOff-the-shelf MCP-compatible applications are unlikely to have support for this custom transport,\nso this solution is more appropriate for service-to-service communication rather than for end users.\n\n<details>\n\n<summary><b>Python server example</b></summary>\n\n```python\nimport sys\nfrom mcp.client.stdio import StdioServerParameters\nfrom mcp_lambda import stdio_server_adapter\n\nserver_params = StdioServerParameters(\n command=sys.executable,\n args=[\n \"-m\",\n \"my_mcp_server_python_module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n)\n\n\ndef handler(event, context):\n return stdio_server_adapter(server_params, event, context)\n```\n\nSee a full, deployable example [here](examples/servers/time/).\n\n</details>\n\n<details>\n\n<summary><b>Typescript server example</b></summary>\n\n```typescript\nimport { Handler, Context } from \"aws-lambda\";\nimport { stdioServerAdapter } from \"@aws/run-mcp-servers-with-aws-lambda\";\n\nconst serverParams = {\n command: \"npx\",\n args: [\n \"--offline\",\n \"my-mcp-server-typescript-module\",\n \"--my-server-command-line-parameter\",\n \"some_value\",\n ],\n};\n\nexport const handler: Handler = async (event, context: Context) => {\n return await stdioServerAdapter(serverParams, event, context);\n};\n```\n\nSee a full, deployable example [here](examples/servers/weather-alerts/).\n\n</details>\n\n<details>\n\n<summary><b>Python client example</b></summary>\n\n```python\nfrom mcp import ClientSession\nfrom mcp_lambda import LambdaFunctionParameters, lambda_function_client\n\nserver_params = LambdaFunctionParameters(\n function_name=\"my-mcp-server-function\",\n region_name=\"us-east-2\",\n)\n\nasync with lambda_function_client(server_params) as (\n read_stream,\n write_stream,\n):\n async with ClientSession(read_stream, write_stream) as session:\n await session.initialize()\n tool_result = await session.call_tool(\"echo\", {\"message\": \"hello\"})\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/python/server_clients/lambda_function.py).\n\n</details>\n\n<details>\n\n<summary><b>Typescript client example</b></summary>\n\n```typescript\nimport {\n LambdaFunctionParameters,\n LambdaFunctionClientTransport,\n} from \"@aws/run-mcp-servers-with-aws-lambda\";\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\n\nconst serverParams: LambdaFunctionParameters = {\n functionName: \"my-mcp-server-function\",\n regionName: \"us-east-2\",\n};\n\nconst client = new Client(\n {\n name: \"my-client\",\n version: \"0.0.1\",\n },\n {\n capabilities: {\n sampling: {},\n },\n }\n);\n\nconst transport = new LambdaFunctionClientTransport(serverParams);\nawait client.connect(transport);\n```\n\nSee a full example as part of the sample chatbot [here](examples/chatbots/typescript/src/server_clients/lambda_function.ts).\n\n</details>\n\n## Related projects\n\n- To write custom MCP servers in Lambda functions,\n see the [MCP Lambda Handler](https://github.com/awslabs/mcp/tree/main/src/mcp-lambda-handler) project.\n- To invoke existing Lambda functions as tools through a stdio MCP server,\n see the [AWS Lambda Tool MCP Server](https://awslabs.github.io/mcp/servers/lambda-tool-mcp-server/) project.\n\n## Considerations\n\n- This library currently supports MCP servers and clients written in Python and Typescript.\n Other languages such as Kotlin are not supported.\n- This library only adapts stdio MCP servers for Lambda, not servers written for other protocols such as SSE.\n- This library does not maintain any MCP server state or sessions across Lambda function invocations.\n Only stateless MCP servers are a good fit for using this adapter. For example, MCP servers\n that invoke stateless tools like the [time MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/time)\n or make stateless web requests like the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch).\n Stateful MCP servers are not a good fit, because they will lose their state on every request.\n For example, MCP servers that manage data on disk or in memory such as\n the [sqlite MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite),\n the [filesystem MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem),\n and the [git MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/git).\n- This library does not provide mechanisms for managing any secrets needed by the wrapped\n MCP server. For example, the [GitHub MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/github)\n and the [Brave search MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)\n require API keys to make requests to third-party APIs.\n You may configure these API keys as\n [encrypted environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars-encryption.html)\n in the Lambda function's configuration. However, note that anyone with access to invoke the Lambda function\n will then have access to use your API key to call the third-party APIs by invoking the function.\n We recommend limiting access to the Lambda function using\n [least-privilege IAM policies](https://docs.aws.amazon.com/lambda/latest/dg/security-iam.html).\n If you use an identity-based authentication mechanism such as OAuth, you could also store and retrieve API keys per user but there are no implementation examples in this repository.\n\n## Deploy and run the examples\n\nSee the [development guide](DEVELOP.md) for instructions to deploy and run the examples in this repository.\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n",
"bugtrack_url": null,
"license": "Apache License (2.0)",
"summary": "Run Model Context Protocol (MCP) servers with AWS Lambda",
"version": "0.3.3",
"project_urls": {
"Issues": "https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda/issues",
"Repository": "https://github.com/awslabs/run-model-context-protocol-servers-with-aws-lambda"
},
"split_keywords": [
"aws",
" lambda",
" mcp",
" modelcontextprotocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "289a909f10b70ebac4bc6a6ea3dcadefa9ca1b19bd7818a27309cd62f5c14255",
"md5": "94097b297b05406200beba1b7f04ae5f",
"sha256": "8b346f362e50f45e00733d3794a1373119ff4b50bdc7545257651079b1270852"
},
"downloads": -1,
"filename": "run_mcp_servers_with_aws_lambda-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94097b297b05406200beba1b7f04ae5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 21170,
"upload_time": "2025-07-29T18:23:40",
"upload_time_iso_8601": "2025-07-29T18:23:40.568190Z",
"url": "https://files.pythonhosted.org/packages/28/9a/909f10b70ebac4bc6a6ea3dcadefa9ca1b19bd7818a27309cd62f5c14255/run_mcp_servers_with_aws_lambda-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a97124f565b5b4a8de4b6b5667bd5870ac091a4dea70b3d8f5e9e85da161e852",
"md5": "3e538b41040b7d6e2191d4f907b284db",
"sha256": "39406b901c1d484c59c8f71430f5a4ca59f1b539c0947634c42741fad0efc62f"
},
"downloads": -1,
"filename": "run_mcp_servers_with_aws_lambda-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "3e538b41040b7d6e2191d4f907b284db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 105388,
"upload_time": "2025-07-29T18:23:41",
"upload_time_iso_8601": "2025-07-29T18:23:41.924179Z",
"url": "https://files.pythonhosted.org/packages/a9/71/24f565b5b4a8de4b6b5667bd5870ac091a4dea70b3d8f5e9e85da161e852/run_mcp_servers_with_aws_lambda-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 18:23:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "awslabs",
"github_project": "run-model-context-protocol-servers-with-aws-lambda",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "run-mcp-servers-with-aws-lambda"
}
JSON
