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

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

12 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: xây MCP server và client — 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.

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.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: int và 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ệnh mcp, gồm các lệnh được README nêu như mcp dev, mcp run và 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 dev mở 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 Client cũ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

  1. Chuẩn bị PythonCài Python 3.11 trở lên và mở terminal
  2. Cài gói MCPCài SDK cùng CLI bằng uv hoặc pip
  3. Tạo serverViết tool và resource trong server.py
  4. Chạy kiểm thửMở server bằng MCP Inspector
  5. Chạy qua HTTPKhởi động server Streamable HTTP để client kết nối
  6. 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:

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

Lệ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:

Terminal
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:

Terminal
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:

Terminal
pip install mcp

README 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:

Terminal
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:

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}!"

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:

Terminal
uv run mcp dev server.py

Lệ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:

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

Lệ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:

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 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:

Terminal
uv run mcp dev server.py

server 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:

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

client có thể kết nối tới http://localhost:8000/mcp. Đoạn client trong README phải in:

Python
{'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:

Terminal
uv run mcp dev server.py

Trong 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:

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

Sau đó dùng client gọi:

Python
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.

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

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ể.

Chuyển nhanh tới mục

  1. I.modelcontextprotocol/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ị thư mục làm việc
    2. B.Cài SDK và CLI
    3. C.Tạo server đầu tiên
    4. D.Mở server trong 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 tạo tool tính nhanh đơn hàng
    2. B.Nhân viên văn phòng tra cứu một resource chuẩn hóa
    3. C.Dev xây ứng dụng Python gọi server nội bộ
    4. D.Đội phát triển thử tool trước khi tích hợp LLM
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Python thấp hơn 3.11
    2. B.Có SDK nhưng không có lệnh mcp
    3. C.Chạy sai thư mục hoặc sai tên file
    4. D.Client không kết nối được tới HTTP server
    5. E.Tool trả về kết quả khác 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ỏ.