MCP 是什麼？和 API 差在哪、怎麼選，再一步步部署自己的 MCP Server

你的服務 ─ API ─┬─ 網站、App、排程程式（固定流程）
                └─ MCP Server ─ Claude / ChatGPT / 其他 AI（彈性需求）

curl -LsSf https://astral.sh/uv/install.sh | sh

uv init guava-notes
cd guava-notes
uv add "mcp[cli]"

import json
import logging
import os
from datetime import datetime
from pathlib import Path

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

NOTES_FILE = Path(os.environ.get("NOTES_FILE", "notes.json"))

mcp = MCPServer("guava-notes")


def load_notes() -> list[dict]:
    if NOTES_FILE.exists():
        return json.loads(NOTES_FILE.read_text(encoding="utf-8"))
    return []


def save_notes(notes: list[dict]) -> None:
    NOTES_FILE.write_text(json.dumps(notes, ensure_ascii=False, indent=2), encoding="utf-8")


@mcp.tool()
def add_note(title: str, content: str) -> str:
    """新增一則筆記。

    Args:
        title: 筆記標題
        content: 筆記內容
    """
    notes = load_notes()
    notes.append({
        "id": len(notes) + 1,
        "title": title,
        "content": content,
        "created_at": datetime.now().isoformat(timespec="seconds"),
    })
    save_notes(notes)
    logger.info("added note %s", title)
    return f"已新增筆記 #{len(notes)}：{title}"


@mcp.tool()
def search_notes(keyword: str) -> str:
    """用關鍵字搜尋筆記的標題與內容。

    Args:
        keyword: 要搜尋的關鍵字
    """
    hits = [n for n in load_notes() if keyword in n["title"] or keyword in n["content"]]
    if not hits:
        return f"找不到包含「{keyword}」的筆記。"
    return "\n".join(f"#{n['id']} {n['title']}：{n['content']}" for n in hits)


if __name__ == "__main__":
    mcp.run()

claude mcp add guava-notes -- uv --directory /你的絕對路徑/guava-notes run server.py

幫我記一則筆記：週五下午三點前要交季報

import hmac
import os

from mcp.server.transport_security import TransportSecuritySettings

from server import mcp

TOKEN = os.environ["MCP_TOKEN"]
DOMAIN = os.environ.get("MCP_DOMAIN", "mcp.example.com")

# 只接受來自你自己網域的請求
security = TransportSecuritySettings(
    allowed_hosts=[DOMAIN, f"{DOMAIN}:*", "127.0.0.1:*", "localhost:*"],
)
mcp_app = mcp.streamable_http_app(transport_security=security)


async def app(scope, receive, send):
    """檢查 Authorization: Bearer <token>，沒帶對就回 401。"""
    if scope["type"] == "http":
        headers = dict(scope["headers"])
        given = headers.get(b"authorization", b"")
        if not hmac.compare_digest(given, f"Bearer {TOKEN}".encode()):
            await send({"type": "http.response.start", "status": 401,
                        "headers": [(b"content-type", b"text/plain")]})
            await send({"type": "http.response.body", "body": b"Unauthorized"})
            return
    await mcp_app(scope, receive, send)

uv add uvicorn
MCP_TOKEN=換成一串很長的亂碼 uv run uvicorn http_app:app --port 8000

[Unit]
Description=Guava Notes MCP Server
After=network.target

[Service]
WorkingDirectory=/opt/guava-notes
Environment=MCP_TOKEN=你的Token
Environment=MCP_DOMAIN=mcp.example.com
Environment=NOTES_FILE=/opt/guava-notes/notes.json
ExecStart=/root/.local/bin/uv run uvicorn http_app:app --host 127.0.0.1 --port 8000 --proxy-headers --forwarded-allow-ips=127.0.0.1
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now guava-notes
sudo systemctl status guava-notes

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

claude mcp add --transport http guava-notes https://mcp.example.com/mcp \
  --header "Authorization: Bearer 你的Token"