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

python-sdk: xây MCP server và client bằng Python — hướng dẫn cài đặt và dùng

12 phút đọcCập nhật
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 MCP server cung cấp tool, resource, prompt và xây client kết nối tới các server đó. Repo yêu cầu Python 3.11 trở lên; cài đặt khá gọn bằng uv hoặc pip.

Repo này là SDK Python chính thức cho Model Context Protocol (MCP), một chuẩn giúp ứng dụng LLM sử dụng dữ liệu và chức năng từ các server bên ngoài. Với gói Python mcp, bạn có thể viết server cung cấp công cụ, tài nguyên và prompt cho MCP host, hoặc viết client để kết nối tới MCP server khác.

Điểm đáng giá là SDK xử lý phần giao tiếp giao thức, kiểm tra dữ liệu và tạo schema từ type hint Python. Bạn chỉ cần viết các hàm Python có kiểu dữ liệu rõ ràng cùng docstring. Repo hiện có khoảng 24.844 sao và 4.122 fork, dùng giấy phép MIT.

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 API riêng vào ứng dụng LLM theo một cách chuẩn hóa. Người mới cũng có thể bắt đầu bằng server có một tool cộng hai số, sau đó mở rộng dần.

Thư viện

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.

★ 25kPythonMIT
Xem repo trên GitHub

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

  • Xây MCP server bằng Python: Bạn có thể tạo server để LLM gọi các hàm nghiệp vụ, đọc dữ liệu hoặc nhận prompt. Ví dụ, một công ty có thể đưa hàm tra cứu đơn hàng vào server để ứng dụng LLM sử dụng khi trả lời khách.

  • Cung cấp tool cho MCP host: Tool là các hàm mà mô hình hoặc ứng dụng LLM có thể gọi. SDK dùng type hint như a: int và b: int để suy ra schema, nên bạn không phải tự viết JSON Schema hay phần phân tích request.

  • Cung cấp resource: Resource phù hợp với dữ liệu được định danh bằng URI. README minh họa resource mẫu greeting://{name}, trong đó tên được truyền vào URI để tạo lời chào tương ứng.

  • Viết MCP client: Cùng một gói có thể kết nối tới MCP server. Client có thể gọi tool và đọc kết quả có cấu trúc, phù hợp khi bạn muốn xây một ứng dụng Python điều phối nhiều server MCP.

  • Hỗ trợ nhiều transport: SDK hỗ trợ stdio, Streamable HTTP và SSE. Bạn có thể chạy server cục bộ qua subprocess hoặc phục vụ server qua HTTP khi triển khai.

  • Có công cụ dòng lệnh đi kèm: Extra cli bổ sung lệnh mcp, gồm các lệnh mcp dev, mcp run và mcp install. Nhờ đó, bạn có thể chạy thử server, mở server qua transport cụ thể hoặc dùng các tác vụ CLI được SDK cung cấp.

  • Tự xử lý phần giao thức: Bạn không phải tự viết phần parsing request, validation hay protocol handling cho ví dụ cơ bản. Đây là lợi ích lớn khi muốn tập trung vào logic nghiệp vụ thay vì chi tiết kết nối giữa LLM host và server.

  • Dùng được cho server và client trong cùng hệ sinh thái: Nếu sản phẩm của bạn vừa cần công bố dữ liệu qua MCP vừa cần gọi các server khác, không cần ghép hai thư viện không liên quan. SDK này cung cấp cả hai phía.

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

  • Python 3.11 trở lên. Đây là yêu cầu được ghi rõ trong README. Nếu máy đang dùng Python thấp hơn, bạn cần cài phiên bản phù hợp trước khi cài gói.

  • Một môi trường Python có thể cài gói. README đưa ra hai lựa chọn là uv hoặc pip. README không ghi chi tiết cách cài Python, uv hay pip, nên bạn cần chuẩn bị sẵn một trong hai công cụ này.

  • Mã nguồn server hoặc client Python. Để thử nhanh, bạn sẽ tạo file server.py theo ví dụ trong README. Khi viết client, bạn cần có một server đang chạy để client kết nối.

  • MCP Inspector nếu muốn kiểm tra server trực quan. README hướng dẫn mở server trong MCP Inspector bằng uv run mcp dev server.py. Tài liệu không nêu yêu cầu phần cứng đặc biệt hay GPU.

  • Không có API key nào được nêu trong README cho ví dụ cơ bản. Ví dụ chỉ cộng hai số và tạo lời chào. Nếu server riêng của bạn gọi dịch vụ khác, yêu cầu về key sẽ phụ thuộc vào dịch vụ đó, nhưng README của repo không mô tả phần này.

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

  1. Chuẩn bị PythonKiểm tra máy có Python 3.11 trở lên
  2. Cài gói mcpCài SDK và tùy chọn CLI bằng uv hoặc pip
  3. Tạo server.pyViết một server có tool và resource mẫu
  4. Chạy server thửMở server bằng MCP Inspector
  5. Chạy qua HTTPPhục vụ server để client có thể kết nối
  6. Viết clientGọi tool và in kết quả có cấu trúc

A.Chuẩn bị Python

Cài hoặc chọn một môi trường Python có phiên bản từ 3.11. README chỉ nêu yêu cầu phiên bản, không cung cấp lệnh kiểm tra phiên bản cụ thể. Vì vậy, hãy kiểm tra bằng công cụ Python bạn đang dùng trước khi cài.

Tạo một thư mục làm việc riêng cho ví dụ, sau đó mở terminal tại thư mục đó. Bạn có thể lấy mã nguồn repo bằng lệnh phổ thông dưới đây nếu muốn xem đầy đủ ví dụ, tài liệu và test:

Terminal
git clone https://github.com/modelcontextprotocol/python-sdk.git
cd python-sdk

Lệnh đầu tiên tải mã nguồn về máy. Lệnh thứ hai đi vào thư mục repo. Tuy nhiên, để dùng gói từ môi trường cài đặt, bạn không bắt buộc phải clone repo; README có hướng dẫn cài trực tiếp bằng uv hoặc pip.

B.Cài gói mcp

README đưa ra lệnh cài có thêm extra cli như sau:

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

uv add thêm gói mcp cùng extra cli vào project. Phần cli cung cấp lệnh mcp với các tác vụ mcp dev, mcp run và mcp install.

Nếu bạn không cần công cụ dòng lệnh, README nói có thể cài gói mcp thuần. README không đưa ra lệnh riêng cho trường hợp này ngoài việc giải thích rằng có thể bỏ extra cli. Với một lệnh chạy thử không cần thêm gói vào project, README cũng nêu cách dùng:

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

Dấu ... ở đây là phần đại diện cho lệnh mcp cụ thể. Khi dùng lệnh thật, bạn thay bằng dev, run hoặc tác vụ phù hợp. Người mới thường vấp ở chỗ đặt sai dấu ngoặc kép quanh mcp[cli]; hãy giữ đúng cách viết trong README.

C.Tạo server.py

Tạo file server.py trong thư mục làm việc và chép đúng ví dụ 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}!"

Đoạn mã tạo một server tên Demo. Hàm add trở thành một tool nhận hai số nguyên và trả về tổng. Hàm greeting trở thành resource có URI mẫu greeting://{name}.

Bạn cần lưu đúng tên file là server.py nếu muốn dùng nguyên các lệnh trong README. Hai dấu gạch dưới trong docstring không phải phần bắt buộc để cộng số, nhưng docstring giúp mô tả chức năng cho hệ thống. Type hint int và str cũng quan trọng vì SDK dùng chúng để tạo schema và kiểm tra dữ liệu.

D.Chạy server bằng MCP Inspector

Từ terminal đang mở tại thư mục chứa server.py, chạy:

Terminal
uv run mcp dev server.py

Lệnh này khởi động server ở chế độ phát triển và mở nó trong MCP Inspector. Nếu terminal báo không tìm thấy server.py, nguyên nhân thường là bạn đang đứng sai thư mục hoặc đặt tên file khác. Hãy chuyển terminal về đúng thư mục chứa file trước khi chạy.

Trong Inspector, gọi tool add với a=1 và b=2. Theo README, kết quả nhận được là 3. Đây là cách kiểm tra nhanh cả phần khai báo tool, schema được suy ra từ type hint và việc gọi hàm.

E.Chạy server qua Streamable HTTP

Để phục vụ server.py qua HTTP, chạy đúng lệnh:

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

README cho biết URL tương ứng để client kết nối là http://localhost:8000/mcp. Bạn cần giữ terminal này đang chạy trong lúc thử client. Nếu đóng terminal hoặc tiến trình dừng, client sẽ không thể gọi tool.

Lệnh --transport streamable-http chọn transport Streamable HTTP. SDK cũng hỗ trợ stdio và SSE, nhưng README chỉ đưa lệnh cụ thể cho Streamable HTTP trong ví dụ client này. Không nên tự đổi tên cờ nếu chưa kiểm tra tài liệu tương ứng.

F.Viết client gọi tool

Tạo một file Python khác, hoặc chạy đoạn mã này trong môi trường có gói mcp:

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

Client mở kết nối tới URL HTTP của server, gọi tool có tên add và truyền hai tham số a và b. Kết quả được in từ structured_content, dự kiến là {'result': 3} theo README.

Hãy chạy server HTTP trước rồi mới chạy client. Nếu server không ở cổng hoặc đường dẫn mặc định, URL trong Client phải khớp với nơi server đang phục vụ. README cũng cho biết Client có thể khởi chạy server cục bộ như một subprocess stdio hoặc nhận transport tùy chỉnh, nhưng không đưa thêm đoạn lệnh chi tiết cho các trường hợp đó.

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

Có ba dấu hiệu rõ ràng để xác nhận ví dụ hoạt động:

  • Sau khi chạy uv run mcp dev server.py, server mở được trong MCP Inspector.
  • Khi gọi tool add với a=1, b=2, kết quả trả về là 3.
  • Sau khi chạy server bằng Streamable HTTP và chạy client, terminal của client in ra {'result': 3} từ result.structured_content.

Bạn nên kiểm tra theo đúng thứ tự. Nếu Inspector không mở, kiểm tra lại việc cài extra cli. Nếu client không kết nối, kiểm tra server HTTP còn chạy và URL có đúng là http://localhost:8000/mcp hay không.

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

A.Chủ shop muốn đưa thao tác tính toán vào trợ lý

Một chủ shop có thể bắt đầu với những tool đơn giản như tính tổng tiền, tính số lượng hàng hoặc kiểm tra một quy tắc giá. Cách triển khai bám theo ví dụ là tạo một hàm Python có tham số kiểu rõ ràng, thêm decorator @mcp.tool() rồi chạy server trong MCP host hỗ trợ MCP.

Ví dụ, mẫu thao tác đầu tiên có thể là tool add nhận a=1, b=2. Khi gọi tool, kết quả trả về là 3. Với nghiệp vụ thật, phần thân hàm sẽ thay phép cộng bằng logic đã có của cửa hàng. README không mô tả kết nối cơ sở dữ liệu, quản lý đơn hàng hay xác thực người dùng, nên các phần đó cần được thiết kế thêm.

B.Nhân viên văn phòng muốn cung cấp dữ liệu có cấu trúc

Một nhóm có thể dùng resource để cung cấp nội dung theo URI. README minh họa greeting://{name}, trong đó server nhận name rồi trả về Hello, {name}!. Mô hình này có thể giúp bạn hình dung cách tạo resource theo mã định danh, nhưng README chưa cung cấp ví dụ dữ liệu văn phòng như bảng tính, tài liệu hoặc hệ thống chấm công.

Bạn có thể bắt đầu bằng resource mẫu, kiểm tra nó trong MCP Inspector, rồi đọc tài liệu của SDK để thay phần trả lời cố định bằng dữ liệu phù hợp. Cần tránh đưa dữ liệu nhạy cảm vào server thử nghiệm trước khi hiểu rõ quyền truy cập của MCP host.

C.Lập trình viên mới muốn thử MCP trong vài phút

Lập trình viên Python mới có thể tạo server.py với tool và resource mẫu, cài mcp[cli], rồi chạy:

Terminal
uv run mcp dev server.py

Sau đó gọi add với a=1, b=2 trong MCP Inspector. Kết quả 3 cho thấy bạn đã tạo được một MCP server cơ bản mà không cần tự viết JSON Schema, request parsing hoặc validation code.

Đây là cách học tốt vì mỗi phần có vai trò rõ: decorator công bố tool, type hint mô tả tham số, docstring giải thích chức năng, còn SDK xử lý giao thức.

D.Dev muốn tách server và client qua HTTP

Khi muốn thử mô hình triển khai tách rời, chạy server bằng:

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

Sau đó dùng client kết nối tới http://localhost:8000/mcp và gọi:

Python
result = await client.call_tool("add", {"a": 1, "b": 2})
print(result.structured_content)

Kết quả mong đợi là {'result': 3}. Mô hình này phù hợp để hiểu cách một ứng dụng Python gọi tool qua Streamable HTTP, nhưng README chưa nói về triển khai production, reverse proxy, phân quyền hoặc giám sát.

MCP giúp bạn biến các hàm và nguồn dữ liệu Python thành khả năng mà ứng dụng LLM có thể gọi theo chuẩn.

Ông T

MCP server có thể mở dữ liệu và chức năng cho ứng dụng LLM. Hãy kiểm tra kỹ tool nào được công bố, dữ liệu nào được trả về và quyền truy cập trước khi dùng với dữ liệu nội bộ. README không mô tả chi phí dịch vụ, cơ chế xác thực hoặc chính sách lưu dữ liệu.

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

A.Python thấp hơn phiên bản yêu cầu

README yêu cầu Python 3.11 trở lên. Nếu môi trường dùng Python cũ, việc cài hoặc chạy SDK có thể thất bại. Hãy chuyển sang Python đáp ứng yêu cầu rồi chạy lại lệnh cài; README không cung cấp lệnh nâng cấp cụ thể.

B.Không tìm thấy lệnh mcp

Lệnh mcp được thêm bởi extra cli. Nếu bạn chỉ cài gói mcp thuần, các lệnh mcp dev, mcp run và mcp install có thể không có. Cài theo lệnh uv add "mcp[cli]" hoặc dùng uv run --with "mcp[cli]" mcp ... như README hướng dẫn.

C.Không tìm thấy server.py

Lệnh uv run mcp dev server.py cần file server.py ở thư mục hiện tại. Hãy kiểm tra bạn đã lưu file đúng tên và mở terminal tại đúng thư mục. Không tự đổi sang tên khác nếu chưa sửa tên file trong lệnh.

D.Client không kết nối được tới server

Server phải được chạy trước bằng uv run mcp run server.py --transport streamable-http. Client dùng URL http://localhost:8000/mcp, vì vậy hai tiến trình phải dùng đúng địa chỉ và đường dẫn. Nếu đã đóng terminal chạy server, hãy khởi động lại rồi chạy client.

E.Tool trả về dữ liệu không như mong đợi

Trong ví dụ, tool add yêu cầu hai tham số a và b có kiểu int. Hãy gọi đúng tên tham số và truyền giá trị phù hợp, chẳng hạn {"a": 1, "b": 2}. Type hint và docstring nên được giữ chính xác để SDK tạo schema và mô tả tool đúng với logic.

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

Nên chọn repo này nếu bạn muốn xây MCP server hoặc client bằng Python, cần một SDK chính thức và muốn hỗ trợ các transport tiêu chuẩn gồm stdio, Streamable HTTP và SSE. Ví dụ khởi đầu ngắn, cách khai báo tool dễ đọc, và SDK giảm đáng kể phần code giao thức phải tự viết.

Repo cũng phù hợp để thử nghiệm nhanh với MCP Inspector. Lệnh cài đặt có sẵn extra CLI, còn cách tạo server cơ bản chỉ cần một file Python. Với người mới, việc type hint được dùng làm schema giúp giảm lượng cấu hình phải học.

Giới hạn là README chỉ mô tả ví dụ cơ bản. Nó chưa cung cấp trong phần tư liệu này hướng dẫn chi tiết về xác thực, phân quyền, cơ sở dữ liệu, triển khai production, chi phí, bảo vệ dữ liệu hay cách cài Python và uv trên từng hệ điều hành. README cũng không xác nhận riêng việc chạy trên Windows.

Nếu bạn cần một thư viện Python để làm MCP server/client và sẵn sàng đọc thêm tài liệu khi đi vào hệ thống thật, đây là lựa chọn đáng cân nhắc. Nếu chỉ cần một API web thông thường không có nhu cầu tích hợp với LLM host qua MCP, một framework web phù hợp với API truyền thống có thể đơn giản hơn.

4.9/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

Repo này có miễn phí không?

Repo dùng giấy phép MIT. README không nêu chi phí dịch vụ hoặc chi phí vận hành, nên phần chi phí ngoài giấy phép chưa có thông tin trong tư liệu.

Có cần GPU để chạy không?

README chỉ yêu cầu Python 3.11 trở lên và không nêu yêu cầu GPU. Ví dụ server cộng hai số cũng không đề cập phần cứng đặc biệt.

Có chạy được trên Windows không?

Tư liệu được cung cấp không xác nhận riêng việc chạy trên Windows. README chỉ nêu yêu cầu Python 3.11 trở lên và các lệnh cài, chạy bằng uv hoặc pip.

Có cần API key không?

Ví dụ cơ bản không cần API key; nó chỉ tạo tool cộng hai số và resource lời chào. Nếu server của bạn kết nối dịch vụ khác, README này không mô tả yêu cầu key cho trường hợp đó.

SDK này dùng để xây server hay client?

Dùng được cho cả hai. SDK giúp xây MCP server cung cấp tool, resource và prompt, đồng thời cung cấp `Client` để kết nối tới MCP server và gọi tool.

SDK hỗ trợ những cách kết nối nào?

README nêu ba transport tiêu chuẩn là stdio, Streamable HTTP và SSE. Ví dụ cụ thể trong README chạy server qua Streamable HTTP và client kết nối tới `http://localhost:8000/mcp`.

Chuyển nhanh tới mục

  1. I.python-sdk làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Chuẩn bị Python
    2. B.Cài gói mcp
    3. C.Tạo server.py
    4. D.Chạy server bằng MCP Inspector
    5. E.Chạy server qua Streamable HTTP
    6. F.Viết client gọi tool
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop muốn đưa thao tác tính toán vào trợ lý
    2. B.Nhân viên văn phòng muốn cung cấp dữ liệu có cấu trúc
    3. C.Lập trình viên mới muốn thử MCP trong vài phút
    4. D.Dev muốn tách server và client qua HTTP
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Python thấp hơn phiên bản yêu cầu
    2. B.Không tìm thấy lệnh mcp
    3. C.Không tìm thấy server.py
    4. D.Client không kết nối được tới server
    5. E.Tool trả về dữ liệu không như mong đợi
  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ỏ.