python-sdk (MCP): viết MCP server và client bằng Python — 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
python-sdk là bộ công cụ Python chính thức của Model Context Protocol (MCP), cài bằng gói `mcp`. Bạn dùng nó để viết server đưa công cụ, dữ liệu và prompt cho ứng dụng AI, hoặc viết client kết nối vào server MCP bất kỳ. Cài đặt khá dễ nếu bạn đã có Python 3.11 trở lên, chỉ cần một lệnh cài gói rồi chạy file ví dụ 15 dòng.
python-sdk là bộ SDK Python chính thức của Model Context Protocol (MCP). Nó giúp bạn viết MCP server (đưa công cụ, dữ liệu, prompt cho ứng dụng AI dùng) và MCP client (kết nối vào server MCP bất kỳ) bằng Python. Gói cài đặt có tên mcp.
Hình dung thế này: MCP giống một cái ổ cắm chuẩn cho AI. Bạn viết một lần một server, rồi bất kỳ ứng dụng AI nào hỗ trợ MCP đều có thể cắm vào dùng. README mô tả MCP là thứ giống web API, nhưng thiết kế riêng cho các ứng dụng dùng mô hình ngôn ngữ.
Repo hợp với lập trình viên mới biết chút Python, và với người làm văn phòng, kinh doanh có người biết code hỗ trợ. Điểm đáng giá nhất là bạn gần như không phải viết phần kỹ thuật phức tạp. README nói rõ: không cần tự viết JSON Schema, không cần xử lý request, không cần code kiểm tra dữ liệu, không cần lo giao thức. Bạn chỉ viết hàm Python có type hint và docstring. Hiện repo có khoảng 24.841 sao và 4.119 fork, giấy phép MIT.
modelcontextprotocol/python-sdk
SDK Python chính thức của Model Context Protocol: viết MCP server và client chỉ bằng vài hàm Python có type hint, hỗ trợ stdio, Streamable HTTP và SSE.
I.python-sdk làm được gì
Dưới đây là các khả năng chính theo README, kèm lợi ích thực tế.
- Viết MCP server. Bạn đưa ra tools (hành động AI có thể gọi), resources (dữ liệu AI có thể đọc) và prompts (mẫu câu lệnh) tới bất kỳ MCP host nào. Ví dụ: biến một hàm tra cứu tồn kho thành công cụ để trợ lý AI gọi.
- Viết MCP client. Cùng một gói
mcpcũng là client đầy đủ. Bạn có thể viết chương trình Python tự gọi công cụ của một server MCP, không cần qua giao diện chat. - Hỗ trợ đủ các kiểu kết nối chuẩn. README ghi: stdio, Streamable HTTP và SSE. Stdio hợp với server chạy ngay trên máy bạn. Streamable HTTP là kiểu README gọi là transport để triển khai thật (deploy).
- Tự sinh schema từ type hint. Hàm
add(a: int, b: int) -> inttự nó đã là schema. Bạn đỡ phải viết tay phần mô tả dữ liệu, đỡ sai sót. - Công cụ dòng lệnh
mcp(khi cài kèm phầncli). README nhắc ba lệnh:mcp dev,mcp run,mcp install. Trong bài này mình chỉ dùngmcp devvàmcp run, vì README có ví dụ cụ thể cho hai lệnh đó. - Có Inspector để thử. README hướng dẫn mở server của bạn trong MCP Inspector để bấm gọi thử công cụ mà không cần ứng dụng AI nào.
II.Cần chuẩn bị gì
Theo tư liệu, bạn chỉ cần:
- Python 3.11 trở lên. README và file
pyproject.tomlđều yêu cầu như vậy. Python cũ hơn sẽ không cài được. - Công cụ cài gói: README dùng
uv(uv add), và cho phép thay bằngpip(pip install). Chọn một trong hai là đủ. - Một terminal (cửa sổ dòng lệnh) và một trình soạn thảo văn bản hoặc code để tạo file
server.py.
Tư liệu không nói repo cần API key, tài khoản hay phần cứng đặc biệt nào để chạy ví dụ. Hệ điều hành cũng không bị giới hạn trong README. Nếu sau này bạn nối server vào một ứng dụng AI cụ thể, ứng dụng đó có thể có yêu cầu riêng, bạn xem tài liệu của nó.
III.Cài đặt từng bước
- Kiểm tra PythonChắc chắn máy có Python 3.11 trở lên
- Cài gói mcpDùng uv hoặc pip, thêm phần cli để có lệnh mcp
- Tạo server.pyChép đoạn server 15 dòng của README
- Chạy thử bằng InspectorGõ mcp dev server.py rồi gọi công cụ add
A.Kiểm tra phiên bản Python
Mở terminal. Trên Windows bạn có thể mở PowerShell. Gõ lệnh dưới đây để xem phiên bản. README không ghi lệnh này, nhưng đây là lệnh phổ thông. Nếu số hiện ra nhỏ hơn 3.11, bạn cần cài Python mới hơn trước.
python --versionTrên một số máy, lệnh này là python3 --version.
B.Cài gói mcp
README đưa hai cách. Nếu bạn đang có một dự án dùng uv, chạy lệnh đầu. Nếu quen pip, chạy lệnh sau dấu or.
uv add "mcp[cli]" # or: pip install "mcp[cli]"Phần [cli] là phần thêm để có công cụ dòng lệnh mcp (gồm mcp dev, mcp run, mcp install). README ghi rõ: nếu không cần công cụ này, bạn cài gói mcp trơn. Dấu ngoặc kép quanh mcp[cli] là để terminal không hiểu nhầm cặp ngoặc vuông, bạn nên giữ nguyên.
Nếu bạn chỉ muốn chạy thử một lần, không muốn tạo dự án, README có lệnh sau. Chữ ... là phần lệnh mcp bạn muốn chạy tiếp theo.
uv run --with "mcp[cli]" mcp ...C.Tạo file server.py
Tạo một thư mục trống, mở nó trong terminal, rồi tạo file tên server.py với nội dung sau, đúng như README:
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}!"Đây là một server hoàn chỉnh với một tool (add, cộng hai số) và một resource có tham số (greeting://{name}, trả lời lời chào theo tên). Đoạn """...""" ngay dưới tên hàm là mô tả. AI sẽ đọc mô tả này để biết công cụ làm gì, nên bạn hãy viết rõ ràng.
D.Mở server trong Inspector
Trong cùng thư mục, chạy:
uv run mcp dev server.pyLệnh này mở server của bạn trong MCP Inspector. Đây là công cụ riêng của dự án MCP, README chỉ dẫn tới nó chứ không mô tả giao diện chi tiết. Người mới hay vấp ở chỗ: phải đứng đúng thư mục có server.py thì lệnh mới tìm thấy file.
IV.Kiểm tra đã chạy được chưa
Theo README, trong Inspector bạn gọi công cụ add với a=1, b=2 và sẽ nhận về 3. Thấy kết quả đó là server của bạn đã chạy đúng.
Bạn cũng có thể thử phía client. Mở một terminal, chạy server qua HTTP:
uv run mcp run server.py --transport streamable-httpRồi ở một terminal khác (hoặc một file Python khác), chạy client mẫu của README:
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())Nếu in ra {'result': 3} thì cả server lẫn client đều hoạt động. Lưu ý: terminal chạy server phải để nguyên, đừng tắt khi client đang chạy.
V.Dùng vào việc thật
SDK chỉ là bộ khung, nên giá trị nằm ở việc bạn gắn hàm Python của mình vào đó. Dưới đây là các tình huống bám đúng cách README dùng: tool, resource và client.
A.Chủ shop muốn trợ lý AI tra bảng giá
Bạn có một file Python nhỏ tra giá theo mã sản phẩm. Bạn bọc nó bằng @mcp.tool() như hàm add ở trên, ví dụ một hàm nhận mã sản phẩm và trả về giá. Docstring ghi rõ «Tra giá theo mã sản phẩm». Sau đó chạy uv run mcp dev server.py để thử gọi hàm. Kết quả: bạn có một công cụ chuẩn MCP, ứng dụng AI hỗ trợ MCP có thể gọi nó thay vì bạn dán bảng giá vào khung chat mỗi lần. Phần nối vào một ứng dụng AI cụ thể bạn xem tài liệu của ứng dụng đó, vì README không hướng dẫn phần này.
Hai hàm Python có type hint và một docstring đã là một MCP server hoàn chỉnh.
Ông T
B.Nhân viên văn phòng chuẩn hoá lời chào khách hàng
Resource trong ví dụ greeting://{name} cho thấy cách đưa dữ liệu tạo theo tham số. Bạn có thể bắt chước: tạo resource trả về mẫu câu chào, mẫu email, hay nội dung chuẩn của công ty theo tên khách. Bạn thay phần f"Hello, {name}!" bằng nội dung của mình. Kết quả: cùng một nguồn nội dung, ai trong nhóm cũng lấy ra được đúng mẫu.
C.Lập trình viên mới viết client gọi công cụ bằng code
Bạn muốn một script tự gọi công cụ, không cần giao diện chat. Chạy server với --transport streamable-http, rồi dùng Client("http://localhost:8000/mcp") và client.call_tool("add", {"a": 1, "b": 2}) như ví dụ ở trên. Kết quả đọc từ result.structured_content. README nói URL nghĩa là Streamable HTTP, còn Client cũng có thể chạy một server cục bộ qua stdio hoặc nhận transport tự viết. Chi tiết nằm ở trang Clients trong tài liệu chính thức.
D.Dev gom công cụ nội bộ thành một server dùng chung
Trong công ty có vài script Python lẻ tẻ: xuất báo cáo, kiểm tra đơn hàng, tính phí. Bạn gom chúng vào một server.py, mỗi script là một hàm @mcp.tool(). Khi cần chia sẻ cho người khác trong mạng, README gợi ý dùng Streamable HTTP, kiểu transport để triển khai. Kết quả: một chỗ duy nhất để quản lý công cụ, dùng được với mọi MCP host. Phần bảo mật và đăng nhập khi mở ra mạng, tư liệu mình có chưa nói chi tiết, bạn cần đọc tài liệu chính thức trước khi mở cho người ngoài.
Server MCP chạy được mã Python của bạn. Chỉ viết vào đó những hàm bạn thật sự muốn AI được gọi, và đừng để lộ mật khẩu hay key trong code hoặc trong kết quả trả về. Khi mở server ra mạng bằng HTTP, hãy tìm hiểu kỹ cách bảo vệ trước khi cho người khác truy cập.
VI.Lỗi hay gặp và cách xử lý
Lệnh mcp báo không tìm thấy. Nguyên nhân thường là bạn cài gói mcp trơn mà chưa có phần cli. README ghi rõ phần cli mới thêm lệnh mcp. Cách xử lý: cài lại với mcp[cli], hoặc dùng uv run --with "mcp[cli]" mcp ... để chạy một lần.
Cài đặt báo lỗi về phiên bản Python. Repo yêu cầu Python 3.11 trở lên. Kiểm tra bằng python --version. Nếu thấp hơn, cài Python mới rồi thử lại, đừng cố ép cài.
Terminal báo lỗi với mcp[cli] khi không để trong ngoặc kép. Một số terminal hiểu ngoặc vuông theo nghĩa khác. Hãy giữ nguyên dấu ngoặc kép như README viết.
Lệnh mcp dev server.py báo không thấy file. Bạn đang mở terminal sai thư mục. Chuyển vào thư mục có server.py bằng cd, hoặc gõ đường dẫn đầy đủ tới file.
Client không kết nối được tới http://localhost:8000/mcp. Thường là server chưa chạy, hoặc terminal chạy server đã bị tắt. Chạy lại uv run mcp run server.py --transport streamable-http, giữ terminal đó mở, rồi mới chạy client. Nếu vẫn lỗi, kiểm tra xem có chương trình khác đang chiếm cổng không. Cổng 8000 là cổng trong ví dụ README, tư liệu không nói cách đổi cổng.
VII.Có nên dùng không
Điểm mạnh. Đây là SDK chính thức của giao thức, nên chọn nó là an tâm về độ tương thích. Cách viết rất gọn: hàm có type hint và docstring là đủ. Cùng một gói làm được cả server lẫn client, hỗ trợ ba kiểu transport chuẩn. Giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây, có tài liệu riêng, hướng dẫn nâng cấp (migration) và thư mục ví dụ.
Giới hạn. Đây là thư viện cho người viết code, không phải ứng dụng bấm là dùng. Bạn cần biết đủ Python để viết hàm và chạy lệnh. README cũng khá ngắn: các chủ đề như bảo mật khi mở ra mạng, cách nối vào từng ứng dụng AI cụ thể, hay triển khai lên máy chủ đều nằm ở tài liệu chính thức, bạn nên đọc thêm.
Khi nào chọn cách khác. Nếu bạn không biết code và chỉ muốn dùng một công cụ MCP có sẵn, hãy tìm một MCP server đã đóng gói sẵn thay vì tự viết. Nếu bạn viết bằng ngôn ngữ khác Python, hãy tìm SDK của ngôn ngữ đó. Còn nếu bạn là người mới và muốn hiểu MCP từ gốc, ví dụ 15 dòng ở trên là điểm bắt đầu rất hợp lý: chạy được trong vài phút, rồi mở rộng dần từng hàm một.
Câu hỏi thường gặp
python-sdk có miễn phí không?
Có. Repo dùng giấy phép MIT, bạn được dùng và chỉnh sửa theo điều khoản giấy phép. Tư liệu không nhắc tới phí nào để cài hay chạy SDK.
Cần Python phiên bản nào?
Cần Python 3.11 trở lên. README và file pyproject.toml đều ghi yêu cầu này.
Cài bằng lệnh nào?
README ghi `uv add "mcp[cli]"` hoặc `pip install "mcp[cli]"`. Phần `cli` thêm lệnh `mcp`; nếu không cần lệnh đó bạn cài gói `mcp` trơn. Tên gói Python là `mcp`.
Có cần GPU hoặc API key không?
Tư liệu không nhắc tới GPU hay API key cho việc chạy ví dụ server và client trong README. Nếu bạn nối vào một ứng dụng AI hay dịch vụ khác, thì yêu cầu của chúng nằm ở tài liệu của chính chúng.
Chạy được trên Windows không?
README không nêu hạn chế về hệ điều hành, chỉ yêu cầu Python 3.11 trở lên. Tuy vậy tư liệu cũng chưa có thông tin kiểm chứng riêng cho Windows, bạn nên thử bằng ví dụ 15 dòng để chắc chắn.
MCP server và client khác nhau thế nào?
Server là bên đưa ra công cụ, dữ liệu và prompt. Client là bên kết nối vào server để dùng chúng. SDK này có cả hai: README có ví dụ server 15 dòng và client 10 dòng.
Dữ liệu của tôi có an toàn không?
README mô tả MCP là cách đưa dữ liệu và chức năng cho ứng dụng AI theo kiểu bảo mật và chuẩn hoá, nhưng chưa nói chi tiết về xác thực hay phân quyền. Bạn cần đọc tài liệu chính thức và tự cân nhắc trước khi mở server ra mạng hoặc cho nó truy cập dữ liệu nhạy cảm.


