Beginner's Guide to MCP Servers

MCP サーバーの初心者向けガイド

コーディング経験がほとんどない初心者が、Model Context Protocol（MCP）サーバーを理解して構築できるようにするための、シンプルなデモプロジェクトです。

MCP とは？

Model Context Protocol（MCP）は、AI アシスタント（Claude、ChatGPT など）が外部のツールやデータソースに接続するための仕組みです。AI が次のことをできるようにする橋渡し役と考えてください。

• インターネットからリアルタイムの情報を取得する
• ローカルのファイルやアプリケーションを操作する
• 代わりに特定のタスクを実行する

このプロジェクトには、異なる種類の機能を紹介する 2 つの MCP サーバーが含まれています。

含まれるもの

このプロジェクトには 2 つの MCP サーバーが含まれています。

1. モチベーションを高める名言＆タスク管理サーバー（motivational_server.py）

ローカルファイル操作とタスク管理を紹介します。

• Hello ツール：シンプルなあいさつ関数
• ランダムな名言：ローカルの JSON ファイルからモチベーションを高める名言を取得します
• タスク管理：ローカルに保存されたタスクの追加、一覧表示、完了

1. 任意の API サーバー（server.py）

外部 API への接続を紹介します。

• ノルウェー警察の事件情報：ノルウェーの公開 API から警察の事件情報をリアルタイムで取得します
• 株式市場ツール：企業の株式ティッカーを検索し、現在の株価を取得します（無料の Alpha Vantage API キーが必要です）

前提条件

始める前に、次のことを確認してください。

• お使いのコンピューターに Python 3.11 以降がインストールされていること

インストールとセットアップ

手順 1：このプロジェクトをクローンまたはダウンロードする

このプロジェクトをコンピューターにダウンロードし、ターミナルでプロジェクトフォルダーに移動します。

手順 2：仮想環境を作成する

python -m venv .venv

手順 3：仮想環境を有効にする

macOS/Linux の場合：

source .venv/bin/activate

Windows の場合：

.venv\Scripts\activate

手順 4：依存関係をインストールする

pip install -e .

手順 5：（任意）株式市場 API をセットアップする

株式市場機能を使用するには、Alpha Vantage の無料 API キーが必要です。

1. Alpha Vantage にアクセスして、無料の API キーを取得します
2. 環境変数として設定します。

   export ALPHA_VANTAGE_API_KEY=your_api_key_here
   

AI アシスタントでの使い方

Claude Desktop の場合

1. Claude Desktop の設定ファイルを開きます
2. サーバー設定を追加します。

{
  "mcpServers": {
    "HelloServer": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/path/to/your/project",
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "server.py"        
      ],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "demo"
      }
    }
  }
}

その他の MCP クライアントの場合

接続方法については、お使いの MCP クライアントのドキュメントを参照してください。

利用可能なツール

メインサーバーのツール

• hello() - あいさつメッセージを返します
• get_police_incidents() - ノルウェーの最新の警察の事件情報を取得します
• get_incidents_by_district(district_name) - 特定の警察管区の事件情報を取得します
• get_incidents_by_municipality(municipality_name) - 特定の自治体の事件情報を取得します
• search_stock_ticker(company_name) - 企業の株式ティッカーシンボルを検索します
• get_stock_price(symbol) - ティッカーシンボルの現在の株価を取得します

モチベーションサーバーのツール

• hello() - あいさつメッセージを返します
• get_random_quote() - モチベーションを高めるランダムな名言を返します
• add_task(description) - タスクリストに新しいタスクを追加します
• list_tasks(status_filter) - タスクを一覧表示します（必要に応じて「pending」または「complete」で絞り込めます）
• mark_task_complete(task_id) - タスクを完了としてマークします

プロジェクト構成

gritai-basic-mcp-server/
├── server.py              # Main server with API integrations
├── motivational_server.py # Server with local file operations
├── quotes.json           # Motivational quotes database
├── tasks.json            # Task storage file
├── pyproject.toml        # Project configuration
└── README.md            # This file

サーバーのカスタマイズ

名言を追加する

quotes.json を編集して、独自のモチベーションを高める名言を追加します。

{
  "quote": "Your inspiring quote here",
  "author": "Quote Author"
}

ツールを追加する

いずれかのサーバーに新しいツールを追加するには、@mcp.tool() デコレーターを使用します。

@mcp.tool()
def your_new_tool(parameter: str) -> str:
    """Description of what your tool does."""
    # Your tool logic here
    return "Result"

トラブルシューティング

よくある問題

「Module not found」エラー

• 仮想環境が有効になっていることを確認してください
• pip install -e . を実行して依存関係をインストールしてください

株式市場ツールの API エラー

• Alpha Vantage API キーが正しく設定されていることを確認してください
• 無料の API キーにはレート制限があります

ファイルが見つからないエラー

• プロジェクトディレクトリからサーバーを実行していることを確認してください
• quotes.json と tasks.json が存在することを確認してください

ヘルプを得る

• MCP のドキュメントを確認してください
• 実装の詳細については、コード内のコメントを確認してください
• サーバーには、問題の特定に役立つエラー処理が含まれています

次のステップ

これらの例に慣れたら、次のことを試してみましょう。

1. 既存のツールを変更する
2. 独自の API 統合を追加する
3. ローカルファイルを操作するツールを作成する
4. MCP の仕様を調べ、高度な機能を理解する