Fastmcp Lambda Boilerplate
No description available
Ask AI about Fastmcp Lambda Boilerplate
Powered by Claude ยท Grounded in docs
I know everything about Fastmcp Lambda Boilerplate. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
FastMCP Lambda Boilerplate
AWS Lambda์์ MCP ์๋ฒ๋ฅผ ์คํํ๊ธฐ ์ํ ๋ณด์ผ๋ฌํ๋ ์ดํธ ํ๋ก์ ํธ
์ํคํ ์ฒ
flowchart LR
subgraph Client
MCP[MCP Client<br/>Claude, etc.]
end
subgraph Lambda[AWS Lambda]
LWA[Lambda Web Adapter<br/>Response Streaming]
FastMCP[FastMCP 2.0 Server]
LWA --> FastMCP
end
subgraph Endpoints[Endpoints]
Health["/health<br/>ํฌ์ค์ฒดํฌ"]
MCP_EP["/mcp<br/>MCP ํ๋กํ ์ฝ"]
end
MCP -->|HTTP/SSE| LWA
FastMCP --> Health
FastMCP --> MCP_EP
๋์ ์๋ฆฌ
MCP (Model Context Protocol)
MCP๋ AI ๋ชจ๋ธ๊ณผ ์ธ๋ถ ๋๊ตฌ/๋ฐ์ดํฐ ์์ค๋ฅผ ์ฐ๊ฒฐํ๋ ํ์ค ํ๋กํ ์ฝ์ ๋๋ค.
sequenceDiagram
participant Client as MCP Client<br/>(Claude Desktop)
participant Lambda as AWS Lambda
participant Server as FastMCP Server
Client->>Lambda: POST /mcp<br/>{"method": "tools/list"}
Lambda->>Server: HTTP Request
Server-->>Lambda: Tool ๋ชฉ๋ก ๋ฐํ
Lambda-->>Client: SSE Response
Client->>Lambda: POST /mcp<br/>{"method": "tools/call", "name": "greet"}
Lambda->>Server: Tool ์คํ
Server-->>Lambda: ์คํ ๊ฒฐ๊ณผ
Lambda-->>Client: SSE Response
Lambda Web Adapter
AWS Lambda๋ ๊ธฐ๋ณธ์ ์ผ๋ก ์ด๋ฒคํธ ๊ธฐ๋ฐ์ด์ง๋ง, Lambda Web Adapter๋ฅผ ์ฌ์ฉํ๋ฉด ์ผ๋ฐ HTTP ์๋ฒ๋ฅผ Lambda์์ ์คํํ ์ ์์ต๋๋ค.
flowchart LR
subgraph Lambda Runtime
LWA[Lambda Web Adapter<br/>ํฌํธ 8080 ๋ฆฌ์ค๋]
APP[FastMCP App<br/>HTTP ์๋ฒ]
end
REQ[HTTP Request] --> LWA
LWA -->|ํ๋ก์| APP
APP -->|Response| LWA
LWA --> RES[HTTP Response<br/>+ Streaming]
ํต์ฌ ํน์ง:
- Lambda Function URL๋ก ์ง์ HTTP ์์ฒญ ์์
- Response Streaming์ผ๋ก SSE(Server-Sent Events) ์ง์
- ์ปจํ ์ด๋ ์ด๋ฏธ์ง ๊ธฐ๋ฐ์ผ๋ก ๋ณต์กํ ์์กด์ฑ ๊ด๋ฆฌ ๊ฐ๋ฅ
FastMCP 2.0
FastMCP๋ MCP ์๋ฒ๋ฅผ ์ฝ๊ฒ ๊ตฌ์ถํ ์ ์๋ Python ํ๋ ์์ํฌ์ ๋๋ค.
from fastmcp import FastMCP
mcp = FastMCP("my-server", stateless_http=True)
@mcp.tool()
async def greet(name: str) -> str:
"""์ธ์ฌ๋ง์ ๋ฐํํฉ๋๋ค."""
return f"Hello, {name}!"
stateless_http=True: Lambda์ stateless ํ๊ฒฝ์ ๋ง๊ฒ ์ธ์ ์์ด ๋์
์์ฒญ ์ฒ๋ฆฌ ํ๋ฆ
flowchart TB
subgraph 1. ํด๋ผ์ด์ธํธ ์์ฒญ
A[Claude Desktop] -->|MCP ํ๋กํ ์ฝ| B[Function URL]
end
subgraph 2. Lambda ์ฒ๋ฆฌ
B --> C[Lambda Web Adapter]
C --> D[FastMCP Server]
D --> E{์์ฒญ ํ์
}
E -->|tools/list| F[๋ฑ๋ก๋ Tool ๋ชฉ๋ก ๋ฐํ]
E -->|tools/call| G[Tool ํจ์ ์คํ]
end
subgraph 3. ์๋ต
F --> H[JSON Response]
G --> H
H -->|SSE Stream| A
end
๊ธฐ์ ์คํ
| ๊ธฐ์ | ์ฉ๋ |
|---|---|
| FastMCP 2.0 | Python MCP ์๋ฒ ํ๋ ์์ํฌ |
| Lambda Web Adapter | Lambda์์ HTTP ์๋ฒ ์คํ |
| Serverless Framework | Docker ๊ธฐ๋ฐ Lambda ๋ฐฐํฌ |
| Starlette | ASGI ์น ํ๋ ์์ํฌ |
๋น ๋ฅธ ์์
1. ํ๋ก์ ํธ ๋ณต์ฌ
cp -r fastmcp-lambda-boilerplate my-mcp-server
cd my-mcp-server
2. ์์กด์ฑ ์ค์น
# uv ์ฌ์ฉ (๊ถ์ฅ)
uv sync
# ๋๋ pip
pip install -r requirements.txt
3. ๋ก์ปฌ ์คํ
python mcp_server.py
4. ํ ์คํธ
# Health Check
curl http://localhost:8080/health
# Tools List
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
# Tool Call
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "greet", "arguments": {"name": "World"}}}'
AWS Lambda ๋ฐฐํฌ
์ฌ์ ์๊ตฌ์ฌํญ
1. AWS ๊ณ์ ๋ฐ ์๊ฒฉ์ฆ๋ช
AWS ๊ณ์ ๊ณผ IAM ์ฌ์ฉ์์ Access Key๊ฐ ํ์ํฉ๋๋ค.
# AWS CLI ์ค์น (macOS)
brew install awscli
# AWS ์๊ฒฉ์ฆ๋ช
์ค์
aws configure
์ค์ ์ ํ์ํ ์ ๋ณด:
| ํญ๋ชฉ | ์ค๋ช | ์์ |
|---|---|---|
| AWS Access Key ID | IAM ์ฌ์ฉ์ ์ก์ธ์ค ํค | AKIAIOSFODNN7EXAMPLE |
| AWS Secret Access Key | IAM ์ฌ์ฉ์ ์ํฌ๋ฆฟ ํค | wJalrXUtnFEMI/K7MDENG/... |
| Default region | ๋ฐฐํฌํ ๋ฆฌ์ | ap-northeast-2 |
| Default output format | ์ถ๋ ฅ ํ์ | json |
IAM ๊ถํ: Lambda, API Gateway, CloudFormation, S3, CloudWatch Logs, ECR ๊ถํ ํ์
2. Docker ์ค์น
Lambda ์ปจํ ์ด๋ ์ด๋ฏธ์ง ๋น๋์ ํ์ํฉ๋๋ค.
# macOS
brew install --cask docker
# Docker ์คํ ํ์ธ
docker --version
3. Node.js ๋ฐ Serverless Framework
# Node.js ์ค์น (v18 ์ด์ ๊ถ์ฅ)
brew install node
# Serverless Framework ์ ์ญ ์ค์น
npm install -g serverless
# ํ๋ก์ ํธ ์์กด์ฑ ์ค์น
npm install
4. Python ํ๊ฒฝ (๋ก์ปฌ ๊ฐ๋ฐ์ฉ)
# uv ์ค์น (๊ถ์ฅ)
curl -LsSf https://astral.sh/uv/install.sh | sh
# ์์กด์ฑ ์ค์น
uv sync
# ๋๋ pip ์ฌ์ฉ
pip install -r requirements.txt
๋ฐฐํฌ
# ๊ฐ๋ฐ ํ๊ฒฝ ๋ฐฐํฌ
serverless deploy --stage dev
# ํ๋ก๋์
๋ฐฐํฌ
serverless deploy --stage prod
๋ฐฐํฌ ๊ฒฐ๊ณผ
๋ฐฐํฌ ํ Lambda Function URL์ด ์์ฑ๋ฉ๋๋ค:
- Endpoint:
https://{id}.lambda-url.{region}.on.aws/ - MCP Endpoint:
https://{id}.lambda-url.{region}.on.aws/mcp
์ปค์คํฐ๋ง์ด์ง
์๋ก์ด Tool ์ถ๊ฐ
mcp_server.py์ ์๋ก์ด tool ์ถ๊ฐ:
from typing import Annotated
@mcp.tool()
async def my_tool(
param1: Annotated[str, "Parameter description"],
param2: Annotated[int, "Optional parameter"] = 10,
) -> dict:
"""Tool description for MCP clients."""
# Your logic here
return {"result": "success"}
ํ๊ฒฝ ๋ณ์ ์ถ๊ฐ
.envํ์ผ์ ๋ณ์ ์ถ๊ฐserverless.yml์environment์น์ ์ ์ถ๊ฐ:
provider:
environment:
MY_API_KEY: ${env:MY_API_KEY}
์๋ฒ ์ค์ ๋ณ๊ฒฝ
mcp_server.py์์ FastMCP ์ค์ ๋ณ๊ฒฝ:
mcp = FastMCP(
name="my-custom-server",
instructions="Your custom instructions",
stateless_http=True,
)
ํ๋ก์ ํธ ๊ตฌ์กฐ
graph TD
subgraph Core[ํต์ฌ ํ์ผ]
MCP_SERVER[mcp_server.py<br/>FastMCP ์๋ฒ ๋ฉ์ธ]
end
subgraph Deploy[๋ฐฐํฌ ์ค์ ]
DOCKER[Dockerfile<br/>Lambda Web Adapter]
SERVERLESS[serverless.yml<br/>Serverless Framework]
end
subgraph Config[์ค์ ํ์ผ]
REQ[requirements.txt<br/>Python ์์กด์ฑ]
PYPROJECT[pyproject.toml<br/>ํ๋ก์ ํธ ๋ฉํ๋ฐ์ดํฐ]
ENV[.env.example<br/>ํ๊ฒฝ๋ณ์ ํ
ํ๋ฆฟ]
end
subgraph Meta[๋ฉํ ํ์ผ]
GITIGNORE[.gitignore]
README[README.md]
end
MCP_SERVER --> DOCKER
DOCKER --> SERVERLESS
REQ --> DOCKER
MCP ํด๋ผ์ด์ธํธ ์ฐ๊ฒฐ
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"my-server": {
"url": "https://{lambda-url}/mcp",
"transport": "streamable-http"
}
}
}
์ฃผ์์ฌํญ
ARM Mac์์ ๋น๋ ์
Dockerfile์ --platform=linux/amd64๊ฐ ์ค์ ๋์ด ์์ด ARM Mac์์๋ ์ ์์ ์ผ๋ก x86_64 ์ด๋ฏธ์ง๊ฐ ๋น๋๋ฉ๋๋ค.
Lambda ์ ํ์ฌํญ
- Timeout: ๊ธฐ๋ณธ 60์ด (serverless.yml์์ ์กฐ์ ๊ฐ๋ฅ)
- Memory: ๊ธฐ๋ณธ 512MB (serverless.yml์์ ์กฐ์ ๊ฐ๋ฅ)
- Response Streaming: Lambda Function URL๋ก ํ์ฑํ๋จ
Stateless ๋ชจ๋
stateless_http=True ์ค์ ์ผ๋ก Lambda์ stateless ํ๊ฒฝ์ ๋ง๊ฒ ๋์ํฉ๋๋ค.
๋ฌธ์ ํด๊ฒฐ
exec format error
Lambda์์ exec format error ๋ฐ์ ์:
- Dockerfile์ ๋ชจ๋ FROM ๋ฌธ์
--platform=linux/amd64ํ์ธ serverless.yml์architecture: x86_64ํ์ธ
Permission denied
Lambda์์ Permission denied ๋ฐ์ ์:
- Dockerfile์์ ํ์ผ ๊ถํ ์ค์ ํ์ธ
COPY --chmod=644์ฌ์ฉ
Health check ์คํจ
Lambda Web Adapter๊ฐ health check ์คํจ ์:
/health์๋ํฌ์ธํธ๊ฐ{"status": "ok"}๋ฐํํ๋์ง ํ์ธAWS_LWA_READINESS_CHECK_PATH=/health์ค์ ํ์ธ
