Zenn
🐢

自作Pythonライブラリを使ってMCPサーバーを作成してみた

に公開
Docker
Python
Model Context Protocol
Japanese
Claude
tech

はじめに

今回、MCPに慣れるために自作ライブラリを利用してPythonでMCPサーバーを作成してみました。
使用した自作ライブラリは漢字の変換を行うkanjiconvというライブラリです。
これをMCPサーバーとして実装し、Claude Desktopから利用できるようにしました。
kanjiconvのZenn記事はこちらです。

MCPとは？

MCP（Model Context Protocol）は、AI モデルが外部ツールやデータソースと安全にやり取りするためのオープンな標準プロトコルです。詳細はいろいろなところで記事になっているので、ここでは割愛しますが、MCPを使うことで、AIモデルに対して特定の機能を提供するツールを簡単に追加できます。

作成したもの

GitHubのリポジトリは以下になります。
https://github.com/sea-turt1e/kanjiconv_mcp

今回作成したkanjiconv_mcpは、以下の機能を提供します：

  • 漢字→ひらがな変換: 「幽☆遊☆白書は最高の漫画です」→「ゆうゆうはくしょはさいこうのまんがです」
  • 漢字→カタカナ変換: 「幽☆遊☆白書は最高の漫画です」→「ユウユウハクショハサイコウノマンガデス」
  • 漢字→ローマ字変換: 「幽☆遊☆白書は最高の漫画です」→「yuuyuuhakushohasaiikounomangadesu」

Claude Desktopでのデモ

今回のMCPサーバーをClaude Desktopに適用したデモ動画です。
kanjiconvのMCPサーバーを使わないと、「幽☆遊☆白書」のひらがなへの変換は「ゆう☆ゆう☆はくしょ」になってしまいますが、MCPサーバーを使うことで「ゆうゆうはくしょ」と固有名詞を考慮した変換ができます。
デモ動画

技術スタック

  • Python 3.13: Python環境
  • uv: 高速なPython パッケージマネージャー
  • kanjiconv: 日本語変換ライブラリ
  • sudachipy: 形態素解析エンジン
  • Docker: コンテナ化による環境の統一
  • MCP SDK: Claude Desktopとの連携

プロジェクト構成

kanjiconv_mcp/
├── main.py                    # MCPサーバーのメイン実装
├── pyproject.toml            # プロジェクト設定とdependencies
├── requirements.txt          # pip用の依存関係リスト
├── Dockerfile               # uv使用版
├── Dockerfile.pip           # pip使用版（フォールバック）
├── docker-compose.yml       # サービス管理用
├── docker.sh               # Docker操作用のヘルパースクリプト
├── claude_desktop_config.json    # Claude Desktop設定例
|── claude_desktop_config_docker.json # Docker版の設定例
└── test_client.py          # テスト用クライアント

実装のポイント

1. MCPサーバーの基本構造

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

# MCPサーバーインスタンス作成
server = Server("kanjiconv-mcp")

@server.list_tools()
async def list_tools() -> list[Tool]:
    """利用可能なツールのリストを返す"""
    return [
        Tool(
            name="convert_to_hiragana",
            description="Convert Japanese text (including kanji) to hiragana",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Japanese text to convert"},
                    "separator": {"type": "string", "default": "/"},
                    # ... その他のオプション
                },
                "required": ["text"],
            },
        ),
        # ... 他のツール
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    """ツール呼び出しの処理"""
    if name == "convert_to_hiragana":
        request = ConvertRequest(**arguments)
        kanji_conv = get_kanji_conv_instance(
            request.separator, 
            request.use_custom_readings, 
            request.use_unidic, 
            request.sudachi_dict_type
        )
        result = kanji_conv.to_hiragana(request.text)
        return [TextContent(type="text", text=result)]

2. 柔軟な設定オプション

各変換ツールでは以下のオプションをサポートしています：

  • separator: 単語間の区切り文字（デフォルト: "/"）
  • use_custom_readings: カスタム読み辞書の使用
  • use_unidic: UniDicの使用（精度向上）
  • sudachi_dict_type: Sudachi辞書タイプ（full/small/core）

3. Docker化による環境統一

メインのDockerfile（uv使用）

FROM python:3.13-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# システム依存関係のインストール
RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
    pkg-config \
    && rm -rf /var/lib/apt/lists/*

# Rustのインストール
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
    && . /root/.cargo/env
ENV PATH="/root/.cargo/bin:$PATH"

ADD . /app

# uvの設定
WORKDIR /app
RUN uv sync --locked

# 辞書のダウンロード
RUN uv run python -m unidic download

COPY main.py ./

EXPOSE 8000

# 環境変数の設定
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

# MCPサーバーの実行
CMD ["uv", "run", "python", "main.py"]

フォールバック用Dockerfile（pip使用）

FROM python:3.13-slim-bookworm

RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
    pkg-config \
    git \
    && rm -rf /var/lib/apt/lists/*

RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:$PATH"

WORKDIR /app

COPY requirements.txt ./

RUN pip install --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

RUN python -m unidic download

COPY main.py ./
COPY pyproject.toml ./

EXPOSE 8000

ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

CMD ["python", "main.py"]

4. 便利なヘルパースクリプト

docker.shスクリプトで Docker操作を簡素化：

# ビルド（uvを試してからpipにフォールバック）
./docker.sh build

# 明示的にpip版でビルド
./docker.sh build-pip

# テスト実行
./docker.sh test

# クリーンアップ
./docker.sh clean

Claude Desktopでの設定

以下のようにclaude_desktop_config.jsonを設定することで、Claude DesktopでMCPサーバーを利用できます。（筆者はMac環境で実行しました）

ローカル実行版

{
  "mcpServers": {
    "kanjiconv": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/kanjiconv_mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Docker版

{
  "mcpServers": {
    "kanjiconv": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "kanjiconv-mcp:latest"],
      "cwd": "/path/to/kanjiconv_mcp"
    }
  }
}

開発で苦労した点

1. Rust依存関係の問題

sudachipyパッケージはRustで書かれた部分を含むため、Dockerイメージでのビルドが複雑でした。Rustコンパイラのインストールと環境変数の設定が必要でした。

2. uvとpipの使い分け

最新のuvは高速ですが、環境によってはサポートされていない場合があります。そのため、フォールバック機能付きのビルドシステムを構築しました。

実際の使用例

Claude Desktopで以下のような質問ができます：

「今日は良い天気ですね」をトークンごとに"/"で区切って、ひらがなに変換してください。

→ 「きょう/は/よ/い/てんき/です/ね」

「プログラミング言語」をカタカナに変換してください。

→ 「プログラミング/ゲンゴ」

「日本語処理」をローマ字に変換してください。

→ 「nihongo/shori」

まとめ

今回、自作Pythonライブラリを使ってMCPサーバーを構築しました。
こういった自作のライブラリをLLMと連携させたいときに思った以上に簡単に実装できることがわかりました。
MCPを利用することで、AIモデルに特定の機能を簡単に追加できるため、今後もさまざまなツールを開発していきたいと思います。

GitHubで編集を提案

Discussion