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

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

9 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 →

python-sdk (MCP): viết 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.

Thư viện

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.

★ 25kPythonMIT
Xem repo trên GitHub

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 mcp cũ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) -> int tự 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ần cli). README nhắc ba lệnh: mcp dev, mcp run, mcp install. Trong bài này mình chỉ dùng mcp dev và 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ằng pip (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

  1. Kiểm tra PythonChắc chắn máy có Python 3.11 trở lên
  2. Cài gói mcpDùng uv hoặc pip, thêm phần cli để có lệnh mcp
  3. Tạo server.pyChép đoạn server 15 dòng của README
  4. 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.

Terminal
python --version

Trê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.

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

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

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

Terminal
uv run mcp dev server.py

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

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

Rồi ở một terminal khác (hoặc một file Python khác), chạy client mẫu của README:

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

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.

4.8/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à 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.

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.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ở server trong Inspector
  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 trợ lý AI tra bảng giá
    2. B.Nhân viên văn phòng chuẩn hoá lời chào khách hàng
    3. C.Lập trình viên mới viết client gọi công cụ bằng code
    4. D.Dev gom công cụ nội bộ thành một server dùng chung
  6. VI.Lỗi hay gặp và cách xử lý
  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ỏ.