modelcontextprotocol/python-sdk: xây MCP server và client — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về modelcontextprotocol/python-sdk — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: python-sdk: xây MCP server và client bằng Python — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
modelcontextprotocol/python-sdk là SDK Python chính thức cho Model Context Protocol, giúp bạn xây server cung cấp tool, resource, prompt và client kết nối tới các server MCP. Cài đặt khá đơn giản nếu có Python 3.11 trở lên; gói có thêm CLI để chạy, phát triển và cài server.
modelcontextprotocol/python-sdk là SDK Python chính thức để xây dựng MCP server và MCP client. MCP là một giao thức tiêu chuẩn cho phép ứng dụng LLM truy cập dữ liệu và chức năng qua các server được thiết kế riêng, tương tự cách web API cung cấp dữ liệu cho ứng dụng.
Thư viện phù hợp với lập trình viên Python muốn đưa dữ liệu nội bộ, thao tác nghiệp vụ hoặc các hàm tự động hóa vào ứng dụng LLM. Nhân viên văn phòng và chủ shop có thể hưởng lợi gián tiếp khi dev đóng gói các việc như tra cứu dữ liệu, tính toán hoặc gọi quy trình nội bộ thành tool cho AI sử dụng.
Điểm đáng giá nhất là bạn không phải tự viết phần xử lý giao thức, phân tích request hay JSON Schema cho các tham số có type hint. Một vài hàm Python có chú thích kiểu và docstring đã đủ để tạo MCP server có tool và resource.
modelcontextprotocol/python-sdk
SDK Python chính thức để xây MCP server, MCP client và kết nối LLM qua stdio, Streamable HTTP hoặc SSE.
I.modelcontextprotocol/python-sdk làm được gì
Xây MCP server bằng Python: Bạn có thể tạo server cung cấp tools, resources và prompts cho bất kỳ MCP host nào tương thích. Ví dụ, một hàm Python cộng hai số có thể trở thành tool để ứng dụng LLM gọi khi cần.
Xây MCP client: Cùng một gói có thể kết nối tới MCP server. Điều này hữu ích khi bạn muốn viết ứng dụng Python tự động gọi tool, lấy resource hoặc kết hợp nhiều server trong một quy trình.
Hỗ trợ nhiều transport: SDK nói được qua stdio, Streamable HTTP và SSE. Bạn có thể chạy server cục bộ dưới dạng tiến trình con, hoặc phục vụ qua HTTP khi cần triển khai.
Tự tạo schema từ type hint: Với tham số như
a: intvàb: int, SDK có thể dùng thông tin kiểu để xử lý schema. Bạn không cần tự viết JSON Schema cho ví dụ cơ bản.Có CLI đi kèm: Phần cài đặt
mcp[cli]thêm lệnhmcp, gồm các lệnh được README nêu nhưmcp dev,mcp runvàmcp install. Nhờ vậy bạn có thể phát triển, chạy và cài server từ terminal.Kiểm thử server bằng MCP Inspector: Lệnh
mcp devmở server trong MCP Inspector. Đây là cách trực quan để gọi thử tool và xem kết quả trước khi tích hợp với ứng dụng lớn hơn.Kết nối server HTTP bằng URL: Client có thể nhận URL Streamable HTTP, chẳng hạn địa chỉ kết thúc bằng
/mcp. Cách này phù hợp khi server được chạy như một dịch vụ riêng thay vì chỉ chạy cùng máy với client.Kết nối server cục bộ qua stdio: README cho biết
Clientcũng có thể khởi chạy server cục bộ như một subprocess stdio. Đây là lựa chọn tiện cho công cụ cá nhân hoặc server chỉ phục vụ một ứng dụng.
II.Cần chuẩn bị gì
Bạn cần Python 3.11 trở lên. Đây là yêu cầu được ghi trong README và cũng là phiên bản tối thiểu mà dự án khai báo.
Bạn cần một môi trường có thể cài gói Python bằng uv hoặc pip. README đưa ra cả hai cách. Nếu muốn dùng các lệnh mcp dev, mcp run và mcp install, bạn cần cài extra cli bằng mcp[cli]. Nếu chỉ dùng SDK trong mã Python và không cần CLI, README nói có thể cài gói mcp thường.
Bạn cần tạo được một file Python, ví dụ server.py, để viết server. Khi chạy ví dụ HTTP, máy cần có thể dùng cổng cục bộ mà server mở. README không yêu cầu API key, tài khoản dịch vụ, GPU hay phần cứng đặc biệt cho các ví dụ này.
README không nêu hệ điều hành cụ thể. Vì vậy, tài liệu được cung cấp chưa đủ để khẳng định mọi khác biệt khi chạy trên Windows, macOS hoặc Linux. README cũng không nói chi phí sử dụng; chi phí của dịch vụ LLM hoặc hạ tầng bên ngoài, nếu bạn tích hợp thêm, không được mô tả trong tư liệu này.
III.Cài đặt từng bước
- Chuẩn bị PythonCài Python 3.11 trở lên và mở terminal
- Cài gói MCPCài SDK cùng CLI bằng uv hoặc pip
- Tạo serverViết tool và resource trong server.py
- Chạy kiểm thửMở server bằng MCP Inspector
- Chạy qua HTTPKhởi động server Streamable HTTP để client kết nối
- Viết clientGọi tool và đọc kết quả từ URL MCP
A.Chuẩn bị thư mục làm việc
Tạo một thư mục riêng cho ví dụ, sau đó mở terminal tại thư mục đó. Nếu bạn muốn lấy mã nguồn dự án để đọc thêm ví dụ, có thể dùng lệnh clone phổ thông sau:
git clone https://github.com/modelcontextprotocol/python-sdk.git
cd python-sdkLệnh đầu tiên tải mã nguồn SDK về thư mục python-sdk. Lệnh thứ hai chuyển terminal vào thư mục đó. Bạn không bắt buộc phải clone repo nếu chỉ muốn cài gói từ trình quản lý Python; README hướng dẫn cài trực tiếp bằng uv hoặc pip.
Nếu terminal báo không nhận ra git, hãy cài Git hoặc dùng thư mục dự án Python hiện có. README không ghi thêm quy trình cài Git, nên phần này chỉ là bước chuẩn bị thông thường.
B.Cài SDK và CLI
README đưa ra hai cách cài đặt:
uv add "mcp[cli]" # or: pip install "mcp[cli]"Với uv, lệnh thêm gói MCP và phần CLI vào dự án. Phần cli là extra, giúp có lệnh mcp dev, mcp run và mcp install.
Nếu bạn dùng pip, chạy phần lệnh được ghi trong chú thích:
pip install "mcp[cli]"Hãy chạy lệnh trong đúng môi trường Python mà bạn sẽ dùng để chạy server.py. Lỗi thường gặp của người mới là cài vào một Python nhưng chạy bằng Python khác, khiến terminal báo thiếu gói hoặc thiếu lệnh mcp.
Nếu chỉ cần thư viện và không cần CLI, README cho biết có thể cài plain mcp:
pip install mcpREADME cũng nêu cách chạy lệnh một lần mà không cần thêm gói vào dự án:
uv run --with "mcp[cli]" mcp ...Dấu ... trong ví dụ là phần lệnh MCP bạn muốn chạy tiếp, không phải chuỗi cần gõ nguyên văn trong mọi tình huống.
C.Tạo server đầu tiên
Tạo file tên server.py trong thư mục làm việc và chép nội dung sau:
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
"""Greet someone by name."""
return f"Hello, {name}!"Dòng from mcp.server import MCPServer lấy lớp server từ gói mcp. MCPServer("Demo") tạo server tên Demo.
Phần @mcp.tool() biến hàm add thành một tool mà MCP host có thể gọi. Hai tham số a và b có kiểu int, còn kết quả cũng là int. Docstring mô tả ngắn mục đích của tool.
Phần @mcp.resource("greeting://{name}") tạo một resource dạng mẫu. Khi có tên, hàm trả về lời chào tương ứng. Bạn cần lưu ý tên file phải đúng là server.py nếu muốn dùng nguyên các lệnh trong README.
README nhấn mạnh rằng ví dụ này không cần bạn tự viết JSON Schema, code phân tích request, code validation hoặc phần xử lý giao thức. Type hint và docstring đảm nhận phần mô tả cơ bản cho SDK.
D.Mở server trong MCP Inspector
Từ terminal đang đứng trong thư mục có server.py, chạy:
uv run mcp dev server.pyLệnh này chạy server ở chế độ phát triển và mở nó trong MCP Inspector. Nếu bạn mở terminal ở thư mục khác, hãy dùng đường dẫn đúng tới server.py hoặc chuyển về thư mục chứa file trước khi chạy.
Trong Inspector, gọi tool add với a=1 và b=2. Kết quả mong đợi là 3. Đây là kiểm tra trực tiếp cho thấy server đã đăng ký tool và SDK đã xử lý tham số theo type hint.
README không đưa ra thêm lệnh kiểm thử riêng cho resource trong phần ví dụ ngắn. Bạn có thể xem tài liệu bắt đầu và các ví dụ trong repo để biết cách khám phá resource sâu hơn.
E.Chạy server qua Streamable HTTP
Để phục vụ server.py qua HTTP, chạy:
uv run mcp run server.py --transport streamable-httpLệnh mcp run chạy file server. Cờ --transport streamable-http chọn transport Streamable HTTP. Theo ví dụ trong README, server sẽ được client truy cập tại http://localhost:8000/mcp.
Giữ terminal này đang chạy trong lúc thử client. Nếu đóng terminal, server HTTP dừng và client sẽ không thể kết nối tới địa chỉ đó.
F.Viết client gọi tool
Tạo một file Python khác hoặc đặt đoạn mã này trong môi trường có gói mcp:
import asyncio
from mcp import Client
async def main() -> None:
async with Client("http://localhost:8000/mcp") as client:
result = await client.call_tool("add", {"a": 1, "b": 2})
print(result.structured_content) # {'result': 3}
asyncio.run(main())Client nhận URL MCP và mở kết nối trong khối async with. call_tool gọi tool tên add với hai giá trị đầu vào. result.structured_content in ra nội dung có cấu trúc; theo README, kết quả mong đợi là {'result': 3}.
URL trong ví dụ dùng Streamable HTTP, là transport được README mô tả cho triển khai. README cũng cho biết Client có thể khởi chạy server cục bộ qua stdio hoặc nhận custom transport, nhưng không đưa mã đầy đủ cho hai trường hợp đó trong phần hướng dẫn ngắn.
Không đưa API key, mật khẩu hoặc dữ liệu nhạy cảm vào tool, resource hay log khi chưa kiểm tra quyền truy cập. MCP server có thể expose chức năng và dữ liệu cho MCP host, nên hãy giới hạn những gì server được phép cung cấp.
IV.Kiểm tra đã chạy được chưa
Có ba dấu hiệu chính để kiểm tra theo đúng ví dụ README.
Thứ nhất, lệnh cài đặt hoàn tất mà không báo lỗi thiếu phiên bản Python hoặc không tìm thấy gói. Nếu dùng mcp[cli], terminal cần nhận được các lệnh CLI được README nêu.
Thứ hai, khi chạy:
uv run mcp dev server.pyserver xuất hiện trong MCP Inspector. Gọi tool add với a=1, b=2 và nhận 3. Đây là kết quả kiểm tra rõ nhất cho server đầu tiên.
Thứ ba, khi chạy server HTTP bằng:
uv run mcp run server.py --transport streamable-httpclient có thể kết nối tới http://localhost:8000/mcp. Đoạn client trong README phải in:
{'result': 3}Nếu client không kết nối được, trước hết kiểm tra server HTTP còn đang chạy, địa chỉ và đường dẫn /mcp có đúng như ví dụ hay không.
V.Dùng vào việc thật
A.Chủ shop tạo tool tính nhanh đơn hàng
Một dev có thể thay hàm add bằng hàm tính tổng tiền hoặc phí vận chuyển của shop. Các tham số Python có type hint giúp mô tả đầu vào rõ ràng để MCP host gọi tool. Ví dụ trong README chứng minh mô hình cơ bản: khai báo hàm, gắn @mcp.tool(), nhận tham số và trả kết quả.
Sau khi viết server, dev chạy:
uv run mcp dev server.pyTrong MCP Inspector, thử các giá trị đơn hàng và kiểm tra kết quả trước khi đưa server cho ứng dụng LLM. Kết quả nhận được là dữ liệu trả về từ hàm Python, thay vì phải tự viết lớp xử lý giao thức.
B.Nhân viên văn phòng tra cứu một resource chuẩn hóa
Một phòng ban có thể đóng gói các nội dung ít thay đổi thành resource. Ví dụ greeting://{name} trong README cho thấy server có thể nhận một phần biến trong URI rồi trả về nội dung tương ứng.
Dev có thể mở rộng cùng kiểu này cho dữ liệu được phép chia sẻ, sau đó để MCP host đọc resource theo tên phù hợp. README chỉ minh họa resource lời chào, nên cần tự kiểm tra tài liệu dự án trước khi áp dụng cho dữ liệu nghiệp vụ phức tạp.
C.Dev xây ứng dụng Python gọi server nội bộ
Khi có một server chạy qua HTTP, ứng dụng Python có thể dùng Client để gọi tool. Quy trình theo README là chạy:
uv run mcp run server.py --transport streamable-httpSau đó dùng client gọi:
result = await client.call_tool("add", {"a": 1, "b": 2})Kết quả có thể được đưa vào bước tiếp theo của quy trình tự động hóa. Ví dụ của README trả về {'result': 3}, cho thấy client nhận được dữ liệu có cấu trúc thay vì chỉ một chuỗi hiển thị.
D.Đội phát triển thử tool trước khi tích hợp LLM
Một đội dev có thể dùng MCP Inspector làm bước kiểm tra thủ công. Họ mở server bằng mcp dev, gọi từng tool với giá trị đầu vào đại diện cho tình huống thật và xác nhận kết quả.
Cách này giúp phát hiện lỗi ở hàm Python, tên tool, tham số hoặc quyền truy cập trước khi kết nối với MCP host. README mô tả chính xác luồng thử add với a=1, b=2 và nhận 3.
MCP biến các hàm Python và dữ liệu được chọn thành giao diện mà ứng dụng LLM có thể sử dụng.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Python thấp hơn 3.11
SDK yêu cầu Python 3.11 trở lên. Nếu trình cài đặt báo không phù hợp, kiểm tra lại Python đang được terminal sử dụng và chuyển sang môi trường có phiên bản đáp ứng yêu cầu. Không nên tự hạ phiên bản gói khi README không hướng dẫn cách đó.
B.Có SDK nhưng không có lệnh mcp
Nguyên nhân dễ gặp là bạn cài plain mcp nhưng lại muốn dùng mcp dev hoặc mcp run. README nói phần cli mới thêm công cụ dòng lệnh, nên hãy cài mcp[cli] nếu cần CLI.
C.Chạy sai thư mục hoặc sai tên file
Lệnh README dùng server.py. Nếu file có tên khác hoặc terminal đang ở thư mục khác, lệnh có thể không tìm thấy server. Hãy kiểm tra file thực tế và mở terminal tại thư mục chứa file trước khi chạy.
D.Client không kết nối được tới HTTP server
Hãy giữ lệnh uv run mcp run server.py --transport streamable-http đang chạy. Sau đó kiểm tra client dùng đúng địa chỉ http://localhost:8000/mcp như README. Nếu bạn đổi transport, cổng hoặc đường dẫn, mã client cũng phải phù hợp; README không cung cấp cấu hình thay thế chi tiết.
E.Tool trả về kết quả khác mong đợi
Kiểm tra tên tool và dữ liệu truyền vào. Ví dụ chuẩn dùng tên add cùng hai khóa a và b, đều là số nguyên. Khi kiểm tra, hãy bắt đầu bằng đúng cặp a=1, b=2 để tách lỗi môi trường khỏi lỗi logic trong hàm.
VII.Có nên dùng không
Nên dùng nếu bạn đang làm Python và muốn xây MCP server hoặc client theo giao thức chuẩn. SDK có API ngắn, hỗ trợ cả server lẫn client, có CLI, có Inspector cho phát triển và hỗ trợ stdio, Streamable HTTP cùng SSE. Giấy phép của dự án là MIT, và repo hiện có khoảng 24.844 sao cùng 4.122 fork.
Thư viện đặc biệt hợp với đội muốn đưa các hàm nội bộ, resource hoặc quy trình tự động hóa tới nhiều MCP host. Cách dùng type hint để mô tả tham số cũng giúp ví dụ đầu tiên khá gọn.
Giới hạn là README được cung cấp chưa mô tả chi tiết việc xác thực, phân quyền, triển khai production, bảo vệ dữ liệu, chi phí hạ tầng hay cách tích hợp với từng MCP host. Bạn cũng cần tự thiết kế lớp an toàn nếu server chạm tới dữ liệu khách hàng hoặc thao tác có hậu quả thật.
Nếu bạn chỉ cần một script Python chạy độc lập, không cần LLM hoặc MCP host, SDK này có thể là phần phụ không cần thiết. Nếu cần triển khai nghiêm túc, hãy đọc thêm tài liệu bắt đầu, API reference, hướng dẫn client, migration guide và các ví dụ trong repo trước khi chốt kiến trúc.
Câu hỏi thường gặp
modelcontextprotocol/python-sdk có miễn phí không?
Repo dùng giấy phép MIT. README không nêu chi phí sử dụng SDK. Chi phí của các dịch vụ hoặc hạ tầng bên ngoài, nếu có, chưa được đề cập.
Có cần GPU để chạy SDK không?
README chỉ yêu cầu Python 3.11 trở lên và không nêu yêu cầu GPU. Các ví dụ server, client và Inspector không đề cập phần cứng đặc biệt.
Có chạy được trên Windows không?
README được cung cấp không nêu hệ điều hành cụ thể. Vì vậy chưa có đủ thông tin trong tư liệu để khẳng định chi tiết cách chạy trên Windows.
Có cần API key hoặc tài khoản LLM không?
Các ví dụ trong README không yêu cầu API key hay tài khoản LLM. SDK xây MCP server và client; việc kết nối dịch vụ bên ngoài có thể cần cấu hình riêng nhưng chưa được mô tả.
SDK này xây server hay client?
Xây được cả hai. Server có thể expose tools, resources và prompts; client có thể kết nối tới MCP server qua URL, stdio subprocess hoặc custom transport.
Transport nào được hỗ trợ?
README nêu ba transport tiêu chuẩn: stdio, Streamable HTTP và SSE. Ví dụ triển khai HTTP dùng `--transport streamable-http` và URL `http://localhost:8000/mcp`.
Khác gì so với tự viết web API Python?
MCP được thiết kế cho tương tác giữa ứng dụng LLM và server, còn web API thường phục vụ ứng dụng nói chung. SDK tự xử lý phần giao thức và có thể tạo schema cơ bản từ type hint, nhưng README không so sánh trực tiếp với framework web cụ thể.


