Bỏ qua tới nội dung
Ông T.vn

modelcontextprotocol/python-sdk: viết MCP server và client bằng Python — hướng dẫn cài đặt và dùng

10 phút đọcCập nhật

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 →

modelcontextprotocol/python-sdk: viết 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à bộ SDK Python chính thức của Model Context Protocol (MCP), dùng để viết server đưa công cụ và dữ liệu cho ứng dụng AI, hoặc client kết nối tới server MCP. Cài bằng một lệnh uv hoặc pip, cần Python 3.11 trở lên. Server đầu tiên chỉ khoảng 15 dòng code nên người mới cũng làm được.

modelcontextprotocol/python-sdk là bộ SDK Python chính thức cho Model Context Protocol (MCP). Nó giúp bạn viết MCP server để đưa công cụ, dữ liệu và câu lệnh mẫu cho các ứng dụng AI, hoặc viết MCP client để kết nối tới bất kỳ server MCP nào. Gói Python tên là mcp.

MCP bạn có thể hiểu đơn giản như một kiểu web API, nhưng thiết kế riêng cho các mô hình ngôn ngữ lớn (LLM). Thay vì mỗi ứng dụng AI tự nghĩ ra cách nối với dữ liệu của bạn, MCP đặt ra một chuẩn chung. Bạn viết server một lần, các ứng dụng AI hỗ trợ MCP đều dùng được.

Repo này hợp với lập trình viên mới, người làm kỹ thuật trong doanh nghiệp, hay bất kỳ ai biết chút Python và muốn AI gọi được hàm của mình. Điểm đáng giá nhất: bạn không phải viết JSON Schema, không phải tự xử lý request hay kiểm tra dữ liệu. Hai hàm Python có chú thích kiểu và một docstring là đã có một server hoàn chỉnh. Repo hiện có khoảng 24.800 sao và 4.100 fork, giấy phép MIT.

Thư viện

modelcontextprotocol/python-sdk

SDK Python chính thức của Model Context Protocol: viết MCP server và MCP client chỉ với vài hàm Python có chú thích kiểu dữ liệu.

★ 25kPythonMIT
Xem repo trên GitHub

I.python-sdk làm được gì

A.Viết MCP server rất gọn

Bạn khai báo một đối tượng MCPServer, rồi gắn decorator lên hàm Python. Hàm nào thành tool (công cụ AI có thể gọi), hàm nào thành resource (dữ liệu AI có thể đọc). README cũng nhắc server còn có thể phơi ra prompts. Lợi ích thực tế: logic công ty bạn (tính giá, tra đơn, đọc dữ liệu nội bộ) đã nằm sẵn trong hàm Python thì chỉ cần thêm vài dòng là AI dùng được.

B.Kiểu dữ liệu chính là schema

Khi bạn viết a: int, b: int, SDK dùng luôn phần chú thích đó làm schema. README nói rõ bạn không viết JSON Schema, không viết code phân tích request, không viết code kiểm tra dữ liệu, không lo phần giao thức. Người mới đỡ phải học nhiều thứ cùng lúc.

C.Viết MCP client

Cùng một gói mcp còn là client đầy đủ. Lớp Client kết nối tới server qua địa chỉ URL, có thể khởi chạy một server cục bộ như tiến trình con (stdio), hoặc nhận một transport tự viết. Bạn dùng nó khi muốn chính chương trình của mình gọi tool trên một server MCP, thay vì đi qua ứng dụng AI.

D.Hỗ trợ đủ các kiểu kết nối chuẩn

SDK nói được cả ba transport chuẩn: stdio, Streamable HTTP và SSE. README giải thích: địa chỉ URL nghĩa là Streamable HTTP, loại bạn dùng khi triển khai thật. Còn stdio hợp với server chạy ngay trên máy bạn.

E.Công cụ dòng lệnh mcp

Kèm thêm phần cli, bạn có lệnh mcp với các lệnh con mcp dev, mcp run, mcp install. Trong README, hai lệnh mcp dev (mở server trong MCP Inspector để thử) và mcp run (chạy server) có ví dụ cụ thể. Lệnh mcp install chỉ được nhắc tên, README chưa giải thích; muốn dùng, bạn xem tài liệu chính thức của dự án.

II.Cần chuẩn bị gì

Theo tư liệu, bạn cần:

  • Python 3.11 trở lên. Đây là yêu cầu ghi trong README và pyproject.toml.
  • Trình quản lý gói uv hoặc pip. README đưa cả hai cách cài. Nếu chưa có uv, bạn dùng pip đi kèm Python là được.
  • Một terminal. Windows có thể dùng PowerShell, macOS/Linux dùng Terminal. README không giới hạn hệ điều hành.

Tư liệu không nói cần API key, tài khoản hay GPU nào để dùng SDK. Nếu server của bạn gọi dịch vụ bên ngoài thì key của dịch vụ đó là việc riêng của bạn.

Muốn thử server bằng giao diện trực quan, README dùng MCP Inspector (một công cụ riêng của dự án MCP). Lệnh mcp dev mở nó giúp bạn; README không nêu yêu cầu nào thêm, nên nếu máy báo thiếu gì thì bạn xem phần Inspector trong tài liệu chính thức.

III.Cài đặt từng bước

  1. Kiểm tra PythonChắc chắn máy có Python 3.11 trở lên
  2. Cài gói mcpCài `mcp[cli]` bằng uv hoặc pip
  3. Tạo server.pyChép đoạn server mẫu 15 dòng vào một file
  4. Chạy thử với InspectorDùng `mcp dev` để gọi thử tool `add`
  5. Thử clientChạy server bằng HTTP rồi gọi từ một client Python

A.Kiểm tra phiên bản Python

Mở terminal và gõ lệnh dưới đây. Nếu số phiên bản thấp hơn 3.11, bạn cần cài Python mới trước khi làm tiếp.

Terminal
python --version

B.Cài gói mcp

README đưa hai cách tương đương. Dùng uv nếu bạn có sẵn dự án quản lý bằng uv, dùng pip nếu bạn quen cách cổ điển:

Terminal
uv add "mcp[cli]"      # or: pip install "mcp[cli]"

Chú ý hai chỗ người mới hay vấp. Một, giữ nguyên dấu ngoặc kép quanh mcp[cli] để terminal không hiểu nhầm dấu [ ]. Hai, phần cli là thứ cung cấp lệnh mcp. Nếu bạn cài mcp trơn thì sẽ không có lệnh này.

Có thể bạn chỉ muốn thử nhanh mà không tạo dự án. README nói cách sau chạy được mà không cần dự án:

Terminal
uv run --with "mcp[cli]" mcp ...

Thay dấu ... bằng lệnh con bạn cần, ví dụ dev server.py.

C.Tạo file server.py

Tạo một file tên server.py trong thư mục làm việc của bạn, rồi dán đoạn sau:

Python
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 MCP hoàn chỉnh, có một tool (add) và một resource có tham số (greeting://{name}). Docstring không chỉ là ghi chú: nó là phần mô tả để AI hiểu hàm dùng làm gì, nên bạn hãy viết rõ ràng.

D.Mở bằng MCP Inspector

Đứng trong thư mục chứa server.py và chạy:

Terminal
uv run mcp dev server.py

Lệnh này mở server trong MCP Inspector. Ở đó bạn chọn tool add, nhập a=1, b=2 và nhận lại 3.

E.Chạy server qua HTTP và gọi bằng client

Để thử phần client, trước hết chạy server theo kiểu Streamable HTTP. Giữ cửa sổ terminal này mở:

Terminal
uv run mcp run server.py --transport streamable-http

Mở một terminal thứ hai, tạo file client (ví dụ client.py) với nội dung sau:

Python
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())

Rồi chạy file này bằng Python của môi trường đã cài mcp. Nếu bạn cài bằng uv, có thể dùng uv run python client.py.

README ghi rõ địa chỉ mẫu là http://localhost:8000/mcp. Đây là địa chỉ chạy trên máy bạn. Khi đưa server ra ngoài mạng, hãy đọc kỹ tài liệu chính thức về triển khai và xác thực trước, vì server MCP có thể cho AI chạm vào dữ liệu thật của bạn.

IV.Kiểm tra đã chạy được chưa

Có hai dấu hiệu theo đúng README:

  • Với Inspector: sau uv run mcp dev server.py, bạn gọi tool add với a=1, b=2 và nhận kết quả 3.
  • Với client: khi server HTTP đang chạy, chạy file client sẽ in ra {'result': 3}.

Chỉ cần một trong hai cho thấy đúng kết quả là SDK đã cài xong và server của bạn đã hoạt động. Nếu muốn chắc hơn, bạn thử đổi a, b thành số khác và xem kết quả có đúng tổng không.

V.Dùng vào việc thật

Các tình huống dưới đây bám sát những gì README cho thấy: server có tool và resource, client gọi được tool. Phần code mình viết thêm đều theo đúng mẫu trong README.

A.Chủ shop cho AI tính tiền đơn hàng

Bạn bán hàng online, có sẵn quy tắc tính tiền (giá nhân số lượng, cộng phí ship). Bạn biết chút Python hoặc nhờ một bạn dev làm. Thay vì nhắn đi nhắn lại để AI tính tay, bạn viết một tool theo đúng mẫu add:

Python
@mcp.tool()
def order_total(price: int, quantity: int) -> int:
    """Tinh tong tien don hang theo don gia va so luong."""
    return price * quantity

Khi một ứng dụng AI hỗ trợ MCP kết nối server này, nó có thể gọi tool thay vì tự nhẩm. Kết quả là con số tính từ code của bạn, không phải từ trí nhớ của mô hình.

Hai hàm Python có chú thích kiểu và một docstring là đã có một server MCP hoàn chỉnh.

Ông T

B.Nhân viên văn phòng chia sẻ dữ liệu có tham số

Bạn ở bộ phận hành chính, cần một chỗ trả về lời chào hay đoạn văn mẫu theo tên từng khách. Resource trong README đúng loại này: địa chỉ greeting://{name} nhận tên và trả về câu chào. Bạn đổi nội dung trả về thành mẫu thư của công ty mình. Phần {name} trong địa chỉ chính là tham số được truyền vào hàm, nên một hàm phục vụ được cả nghìn khách.

C.Lập trình viên thử server trước khi giao cho đồng nghiệp

Bạn viết xong server và muốn chắc nó chạy đúng trước khi cho ai dùng. Chạy uv run mcp dev server.py, mở Inspector, gọi từng tool với số liệu thật, xem kết quả. Cách này không cần ứng dụng AI nào, và bạn thấy ngay lỗi nằm ở code của mình hay ở chỗ khác.

D.Lập trình viên viết chương trình tự động gọi server MCP

Bạn có một đoạn script chạy hằng ngày và muốn nó dùng tool của một server MCP có sẵn. Dùng Client với địa chỉ server, gọi client.call_tool("tên_tool", {...}) như mẫu trong README, rồi lấy kết quả ở result.structured_content. Không cần ứng dụng AI ở giữa; script của bạn nói chuyện thẳng với server.

VI.Lỗi hay gặp và cách xử lý

A.Báo không tìm thấy lệnh mcp

Nguyên nhân thường gặp: bạn cài mcp trơn thay vì mcp[cli]. README nói phần cli mới thêm lệnh mcp. Cài lại bằng pip install "mcp[cli]" hoặc uv add "mcp[cli]", nhớ giữ dấu ngoặc kép. Nếu chỉ chạy thử một lần, dùng uv run --with "mcp[cli]" mcp ....

B.Cài lỗi hoặc báo sai phiên bản Python

Gói yêu cầu Python 3.11 trở lên. Chạy python --version để xem. Máy có nhiều bản Python thì lệnh python có thể trỏ nhầm bản cũ; kiểm tra lại bản bạn đang dùng trước khi cài.

C.Client báo không kết nối được

Client trong ví dụ trỏ tới http://localhost:8000/mcp. Hãy chắc server đang chạy bằng uv run mcp run server.py --transport streamable-http ở một terminal khác và chưa bị tắt. Nếu server của bạn dùng cổng hoặc đường dẫn khác thì sửa URL cho khớp.

D.Chép code từ bài hướng dẫn cũ rồi không chạy

README nhắc đến trang "What's new in v2" và một hướng dẫn chuyển đổi (migration). Nghĩa là cách viết giữa các phiên bản có thể khác nhau. Khi code từ bài cũ báo lỗi import hay tên lớp, hãy so với ví dụ trong README và đọc trang migration trên tài liệu chính thức của dự án.

E.Tool chạy nhưng AI dùng sai hoặc không biết khi nào dùng

Đây thường không phải lỗi cài đặt mà là mô tả chưa rõ. Docstring và chú thích kiểu là thứ AI đọc để hiểu tool. Hãy viết docstring nói rõ hàm làm gì, tham số nghĩa là gì, và đặt tên hàm dễ hiểu.

VII.Có nên dùng không

Điểm mạnh: đây là SDK chính thức, giấy phép MIT, repo vẫn được cập nhật trong vài tháng gần đây. Viết server rất ngắn, không phải tự lo JSON Schema hay giao thức. Cùng một gói làm được cả server lẫn client, và hỗ trợ đủ stdio, Streamable HTTP, SSE. Cài đặt chỉ một lệnh.

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à chạy. Bạn cần biết Python ở mức cơ bản và dùng được terminal. README chỉ đưa ví dụ ngắn; phần xác thực, triển khai thật, các tính năng nâng cao phải đọc tài liệu chính thức. Tư liệu cũng không nói gì về hiệu năng hay giới hạn tải, nên mình không đánh giá được phần đó.

Khi nào chọn cách khác: nếu bạn không viết code và chỉ muốn dùng một công cụ MCP có sẵn thì bạn tìm server làm sẵn thay vì tự viết. Nếu dự án của bạn không dùng Python thì nên tìm SDK cho ngôn ngữ khác của dự án MCP. Còn nếu bạn muốn AI gọi hàm Python của mình mà không muốn tự xử lý giao thức, repo này là điểm khởi đầu hợp lý.

4.3/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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à sửa theo điều khoản của giấy phép đó. Tư liệu không nhắc đến phí nào cho chính SDK. Chi phí của các dịch vụ bên ngoài mà server của bạn gọi (nếu có) là việc riêng.

Cần cài Python phiên bản nào?

Python 3.11 trở lên, theo cả README lẫn pyproject.toml. Bạn kiểm tra bằng lệnh python --version trước khi cài.

Có cần GPU hay API key không?

Tư liệu không yêu cầu GPU hay API key để cài và chạy server mẫu. Server mẫu chỉ có hàm cộng hai số và một resource chào tên. Nếu server của bạn sau này gọi dịch vụ khác thì key của dịch vụ đó là chuyện riêng.

Chạy được trên Windows không?

README không giới hạn hệ điều hành và không nêu riêng Windows. Cách cài bằng uv hoặc pip là lệnh phổ thông. Tư liệu chưa có thông tin kiểm chứng riêng cho Windows, nên nếu gặp vấn đề bạn xem tài liệu chính thức hoặc mục issues của repo.

Khác nhau giữa `mcp` và `mcp[cli]` là gì?

`mcp[cli]` thêm công cụ dòng lệnh `mcp` với các lệnh con `mcp dev`, `mcp run`, `mcp install`. Cài `mcp` trơn thì bạn vẫn có SDK nhưng không có lệnh này. README khuyên cài `mcp[cli]` nếu bạn cần thử và chạy server nhanh.

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 một cách an toàn và chuẩn hoá. Tư liệu không đi sâu vào bảo mật cụ thể cho từng cách triển khai. Repo có file SECURITY.md, bạn nên đọc khi định đưa server ra ngoài mạng.

Tôi tìm tài liệu chi tiết ở đâu?

Tài liệu chính nằm ở trang chủ dự án: py.sdk.modelcontextprotocol.io. README cho biết có hướng dẫn bắt đầu, phần "What's new in v2", tài liệu tham khảo API và hướng dẫn chuyển đổi phiên bản. Repo cũng có thư mục docs, examples và file CONTRIBUTING.md nếu bạn muốn đóng góp.

Chuyển nhanh tới mục

  1. I.python-sdk làm được gì
    1. A.Viết MCP server rất gọn
    2. B.Kiểu dữ liệu chính là schema
    3. C.Viết MCP client
    4. D.Hỗ trợ đủ các kiểu kết nối chuẩn
    5. E.Công cụ dòng lệnh mcp
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Kiểm tra phiên bản Python
    2. B.Cài gói mcp
    3. C.Tạo file server.py
    4. D.Mở bằng MCP Inspector
    5. E.Chạy server qua HTTP và gọi bằng client
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop cho AI tính tiền đơn hàng
    2. B.Nhân viên văn phòng chia sẻ dữ liệu có tham số
    3. C.Lập trình viên thử server trước khi giao cho đồng nghiệp
    4. D.Lập trình viên viết chương trình tự động gọi server MCP
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Báo không tìm thấy lệnh mcp
    2. B.Cài lỗi hoặc báo sai phiên bản Python
    3. C.Client báo không kết nối được
    4. D.Chép code từ bài hướng dẫn cũ rồi không chạy
    5. E.Tool chạy nhưng AI dùng sai hoặc không biết khi nào dùng
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.