FastMCP 示範伺服器

基於 FastMCP、Python 與 Docker 打造的生產就緒 Model Context Protocol (MCP) 伺服器。

支援三種 MCP 傳輸協定：

• stdio — 適用於 Claude Desktop、Cursor 及任何以子程序方式啟動的 MCP 客戶端
• SSE — 傳統 HTTP 串流（GET /sse）
• Streamable HTTP — 現代 HTTP MCP（POST /mcp）

同時提供 Swagger / OpenAPI 3 文件，與 MCP 端點並排提供。

---

快速開始

1. 安裝依賴

pip install -r requirements.txt
# 或
pip install -e ".[dev]"

2. 本機執行

# stdio（適用於 Claude Desktop / Cursor）
python -m server.main

# HTTP 模式，附 Swagger UI →  http://localhost:8000/api/docs
python -m server.main --transport http

# SSE（傳統）
python -m server.main --transport sse

3. 使用 Docker 執行

# 建置並啟動（HTTP 傳輸 + Swagger UI）
docker compose up --build

# 同時在 8001 埠啟動 SSE sidecar
docker compose --profile sse up --build

# 開發模式（透過 volume mount 即時重載）
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

---

端點網址（HTTP / Docker）

MCP 端點

網址	說明
http://localhost:8000/mcp	MCP Streamable HTTP 端點（所有工具）
http://localhost:8000/math/mcp	僅限數學工具
http://localhost:8000/text/mcp	僅限文字工具
http://localhost:8000/system/mcp	僅限系統工具
http://localhost:8001/sse	SSE 端點（需啟用 sse profile）

文件 & 管理

網址	說明
http://localhost:8000/api/docs	Swagger UI
http://localhost:8000/api/redoc	ReDoc UI
http://localhost:8000/api/openapi.json	OpenAPI 3 結構描述
http://localhost:8000/api/health	健康檢查
http://localhost:8000/api/tools	即時 MCP 工具清單
http://localhost:8000/api/resources	即時 MCP 資源清單
http://localhost:8000/api/prompts	即時 MCP 提示清單

---

Claude Desktop 整合

設定檔位置

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

方式一：stdio（本機程序，不需 Docker）

直接啟動 Python 程序，適合本機開發：

{
  "mcpServers": {
    "fastmcp-demo": {
      "command": "python",
      "args": ["-m", "server.main", "--transport", "stdio"],
      "cwd": "C:\\Users\\Zanehsu\\Desktop\\20260327_fastmcp_server"
    }
  }
}

方式二：HTTP（Docker 執行中）

先執行 docker compose up --build，再設定：

{
  "mcpServers": {
    "fastmcp-demo": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

套用設定

1. 編輯上述設定檔
2. 完全關閉 Claude Desktop（確認系統匣也已退出）
3. 重新啟動 Claude Desktop
4. 在對話中輸入「列出所有可用工具」確認 MCP 已連線

---

Cursor 整合

方式一：HTTP（推薦）

先執行 docker compose up --build，再前往 Cursor 設定 → MCP，新增：

{
  "fastmcp-demo": {
    "url": "http://localhost:8000/mcp"
  }
}

方式二：stdio

{
  "fastmcp-demo": {
    "command": "python",
    "args": ["-m", "server.main", "--transport", "stdio"],
    "cwd": "C:\\Users\\Zanehsu\\Desktop\\20260327_fastmcp_server"
  }
}

---

Antigravity 整合

Antigravity 是 Google 推出的 AI-first IDE，內建 MCP Host 支援，可直接從 MCP Store 安裝或手動設定自訂伺服器。

設定檔位置

平台	路徑
Windows	%USERPROFILE%\.gemini\antigravity\mcp_config.json
macOS / Linux	~/.gemini/antigravity/mcp_config.json

方式一：HTTP（Docker 執行中，推薦）

先執行 docker compose up --build，再編輯設定檔：

{
  "mcpServers": {
    "fastmcp-demo": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

方式二：stdio

{
  "mcpServers": {
    "fastmcp-demo": {
      "command": "python",
      "args": ["-m", "server.main", "--transport", "stdio"],
      "env": {
        "PYTHONPATH": "C:\\Users\\Zanehsu\\Desktop\\20260327_fastmcp_server"
      }
    }
  }
}

套用設定

透過 UI：

1. 在 Antigravity 側邊欄點選 Agent 對話區塊頂部的 ...
2. 選擇 MCP Servers → Manage MCP Servers → View raw config
3. 貼入上述設定並儲存，IDE 會自動重新載入

直接編輯：

1. 直接編輯上述路徑的 mcp_config.json
2. 儲存後重新整理 MCP Servers 清單

---

Kiro 整合

Kiro 是 AWS 推出的 AI 輔助 IDE，原生支援 MCP。

設定檔位置

在你的專案根目錄建立（或編輯）：

.kiro/settings/mcp.json

方式一：HTTP（Docker 執行中，推薦）

先執行 docker compose up --build，再設定：

{
  "mcpServers": {
    "fastmcp-demo": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

方式二：stdio

{
  "mcpServers": {
    "fastmcp-demo": {
      "command": "python",
      "args": ["-m", "server.main", "--transport", "stdio"],
      "cwd": "C:\\Users\\Zanehsu\\Desktop\\20260327_fastmcp_server",
      "transport": "stdio"
    }
  }
}

套用設定

1. 儲存 .kiro/settings/mcp.json
2. 重新開啟 Kiro 或執行指令列區的 MCP: Reload Servers
3. 在 Kiro Agent 對話中確認工具已出現

---

可用功能

工具（Tools）

數學

工具	說明
add	兩數相加
subtract	a 減 b
multiply	兩數相乘
divide	a 除以 b（含除零防護）
factorial	n 的階乘（0–20）
statistics_summary	平均值、中位數、最小值、最大值、標準差

文字

工具	說明
word_count	計算字數、字元數、行數、句子數
transform_case	upper / lower / title / snake / camel 轉換
reverse_text	反轉字串
extract_emails	從文字中擷取電子郵件地址
count_occurrences	計算子字串或正規表達式的出現次數

系統

工具	說明
get_system_info	作業系統、Python 版本、主機名稱
get_current_time	任何 IANA 時區的當前時間
get_memory_usage	程序與系統 RAM 使用量
list_environment_variables	環境變數（敏感值已遮罩）

資源（Resources）

URI	說明
resource://server/info	伺服器元資料（JSON）
resource://server/help	說明文件（Markdown）
data://snapshot/{topic}	動態資料快照：weather、stocks、news、crypto

提示（Prompts）

名稱	說明
analyze_data	資料分析提示範本
code_review	程式碼審查提示範本
explain_concept	概念說明提示範本

---

專案結構

.
├── server/
│   ├── main.py              # 入口點 — 傳輸方式選擇與啟動
│   ├── mcp_server.py        # FastMCP 實例 — 中央登錄
│   ├── tools/
│   │   ├── math_tools.py    # 數學計算工具
│   │   ├── text_tools.py    # 文字處理工具
│   │   └── system_tools.py  # 系統資訊工具
│   ├── resources/
│   │   └── data_resources.py  # 靜態與範本資源
│   ├── prompts/
│   │   └── example_prompts.py # 提示範本
│   └── openapi/
│       └── docs_app.py      # FastAPI Swagger/OpenAPI 輔助應用
├── tests/
│   ├── test_tools.py
│   ├── test_resources.py
│   └── test_prompts.py
├── Dockerfile
├── docker-compose.yml
├── docker-compose.dev.yml
├── pyproject.toml
├── requirements.txt
├── .env.example
└── claude_desktop_config_example.json

---

執行測試

pytest
# 或顯示詳細輸出
pytest -v

---

環境變數

變數	預設值	說明
MCP_TRANSPORT	stdio	傳輸方式：stdio | http | sse
MCP_HOST	0.0.0.0	綁定主機（HTTP/SSE）
MCP_PORT	8000	綁定埠號（HTTP/SSE）
MCP_WITH_DOCS	true	掛載 Swagger UI（僅 HTTP 模式）
MCP_SSE_PORT	8001	SSE sidecar 埠號（Docker）

複製 .env.example → .env 進行本機設定。

---

新增自訂工具

1. 在 server/tools/ 建立新檔案，並宣告自己的 FastMCP 實例：

# server/tools/my_tools.py
from fastmcp import FastMCP

my_mcp = FastMCP(name="My Tools")

@my_mcp.tool()
def greet(name: str) -> str:
    """向某人打招呼。"""
    return f"Hello, {name}!"

2. 在 server/mcp_server.py 中 import 並掛載到指定前綴：

from server.tools.my_tools import my_mcp

mcp.mount("/my", my_mcp)

完成！工具即可透過 /my/mcp 存取，也會出現在主端點 /mcp。