Skip to main content
Glama
northfieldzz

Python MCP Server Blueprint

by northfieldzz
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Python MCP Server Blueprint

uv と ruff を使用した、Python製 Model Context Protocol (MCP) サーバーのテンプレートプロジェクト。 フレームワークとして、Anthropic公式の直感的な高レベルAPIである FastMCP を採用している。

機能・特徴

  • FastMCP: 最小限のコードで MCP Tool, Resource, Prompt を定義可能。

  • uv: 高速なパッケージマネージャーによる依存関係管理と仮想環境構築。

  • ruff: 超高速なリンター＆フォーマッターによるコード品質管理。

Related MCP server: Simple Remote MCP Server

開発の準備

1. 依存関係のインストール

プロジェクトルートディレクトリで以下のコマンドを実行し、仮想環境の構築と依存関係の同期を行う。

uv sync

コード品質の維持 (Ruff)

コードの静的解析 (Lint)

uv run ruff check .

自動修正を実行する場合：

uv run ruff check --fix .

コードのフォーマット

uv run ruff format .

サーバーの起動

標準入出力 (stdio) モードでサーバーを起動する。

uv run python-mcp-server

ビルドとクリーンアップ

パッケージのビルド

配布用パッケージ（WheelおよびSdist）をビルドする。

uv build

プロジェクトのクリーンアップ

ビルド生成物（dist/, build/）、パッケージ情報（*.egg-info）、キャッシュファイル（__pycache__, .ruff_cache）を削除する。

uv run clean-project

MCP クライアントへの登録例 (Claude Desktop)

Claude Desktop でこのサーバーを動作させるには、設定ファイル（通常は %APPDATA%\Claude\claude_desktop_config.json）に以下のように登録する。

{
  "mcpServers": {
    "python-mcp-server-blueprint": {
      "command": "uv",
      "args": [
        "--directory",
        "D:\\Sources\\python_mcp_server_blueprint",
        "run",
        "python-mcp-server"
      ]
    }
  }
}
IMPORTANT

D:\\Sources\\python_mcp_server_blueprint の部分は、実際のプロジェクトの絶対パスに合わせて修正すること。また、Windowsのパス区切り文字は \\ にエスケープする必要がある。

Docker / nerdctl での実行

プロジェクトをコンテナイメージとしてビルドし、実行することができる。

1. イメージのビルド

nerdctl build -t python-mcp-server-blueprint .

2. コンテナの起動

標準入出力 (stdio) モードで起動する場合

標準入出力の対話が必要なため、インタラクティブモード（-i）を有効にして起動する。

nerdctl run -i --rm python-mcp-server-blueprint

SSE (HTTP) モードで起動する場合

ポート 8000 をフォワードし、ホストを 0.0.0.0 に指定して起動する。

nerdctl run -d -p 8000:8000 --name mcp-server python-mcp-server-blueprint --transport sse --host 0.0.0.0

3. 開発用コンテナ（ホットリロード対応）での起動

Dockerfile のマルチステージビルド機能を使用すると、ホスト側のソースコードの変更が自動的にコンテナ内へ反映され、サーバープロセスが自動再起動（ホットリロード）する開発用環境を構築できる。

開発用イメージのビルド

Dockerfile の development ターゲットを指定してビルドする。

nerdctl build --target development -t python-mcp-server-blueprint-dev .

ボリュームマウントによるホットリロード起動

ホストの src ディレクトリをコンテナ内の /app/src にボリュームマウントして起動する。

nerdctl run -d -p 8000:8000 --name mcp-server-dev -v D:\Sources\python_mcp_server_blueprint\src:/app/src python-mcp-server-blueprint-dev

起動後、ホスト側の src/ 配下のコードを書き換えるだけで、コンテナ内のサーバーが自動で再起動して即座に変更が反映される。

Docker Compose での実行

compose.yaml を使用することで、ホットリロード有効の開発用コンテナをより簡単に起動・停止できる。

開発環境の起動 (ホットリロード有効)

# 起動 (初回は自動でビルドされる)
nerdctl compose up -d

# ログの確認 (ホットリロードのログ等)
nerdctl compose logs -f

# 停止
nerdctl compose down

  • Swagger UI: http://localhost:8000/docs

Available Tools

2 tools
calculate_squareA

与えられた数値の2乗を計算する。

ParametersJSON Schema
NameRequiredDescriptionDefault
xYes2乗する整数値

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states only the core operation without discussing side effects, return format, or edge cases. For a pure integer square function, the behavior is essentially fully described, and an output schema exists, but no additional behavioral context is added.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that immediately conveys the tool's purpose with no unnecessary words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema present), the description and schema together provide all essential information. No additional context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already fully describes the parameter 'x' with a clear description ('integer value to square'). The tool description adds no further details about the parameter, so it relies on the schema's 100% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation 'calculate the square of the given number' with a specific verb and resource, and it differentiates itself from the sibling tool 'greet_user' by being a mathematical operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The only sibling tool is unrelated, but the description does not offer any usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greet_userA

ユーザーに挨拶を返す。

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoユーザーの名前Guest

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the basic behavior (returns a greeting) but adds no extra context about side effects, permissions, or edge cases. For a simple read-like operation, this is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that immediately conveys the tool's purpose. There is no redundant information or filler, making it optimally sized and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, a fully documented optional parameter, and an existing output schema, this description is sufficiently complete. The combination of the description and schema provides all necessary information to understand and use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, as the only parameter 'name' is fully documented with a Japanese description. The tool description adds no additional parameter semantics beyond what the schema already provides, earning the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'ユーザーに挨拶を返す' clearly states the tool's action (returns a greeting) and resource (user). It is specific and distinct from the sibling tool calculate_square, which performs a mathematical operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool, when not to use it, or any alternatives. It simply restates the function, leaving the agent to infer usage solely from the tool's name and purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: one performs a numeric calculation, the other provides a greeting. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow the same verb_noun pattern (calculate_square, greet_user), making the naming consistent and predictable.

Tool Count3/5

With only two tools, the server feels thin for most purposes, though as a 'blueprint' it may be intentionally minimal. The count is borderline acceptable.

Completeness2/5

The two tools are unrelated and do not form a cohesive domain, leaving significant gaps for any real-world use case. There is no apparent lifecycle or broader coverage.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Server Template

    amp-rh
    F
    license
    B
    quality
    Not graded
    maintenance
    A production-ready FastMCP server template with modular architecture for building MCP servers with organized tools, resources, and prompts, featuring container support and AI agent documentation system.
    3

  • Simple Remote MCP Server

    ParthSharma1197
    F
    license
    B
    quality
    D
    maintenance
    A template and demonstration project for building, testing, and deploying remote MCP servers using FastMCP and uv. It provides a foundational structure for creating MCP-compliant tools that can be hosted publicly and integrated with LLM agents.
    2

  • MCP Server Creator

    GongRzhe
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables dynamic creation and code generation of MCP servers using FastMCP, with tools for adding custom tools, resources, and generating runnable Python code.
    41
    MIT

  • Template MCP Server

    viktormyrland
    A
    license
    Not graded
    quality
    C
    maintenance
    A production-ready template for developing MCP servers with Python and FastMCP, including example tools like a multiply calculator and code review prompt generator.
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/northfieldzz/python_mcp_server_blueprint'

If you have feedback or need assistance with the MCP directory API, please join our Discord server