MCP Server

MCP サーバー

SearXNG を活用した検索機能やファイルシステム操作など、AI エージェントや LLM 向けのさまざまなツールを提供する、Model Context Protocol（MCP）サーバーの実装です。

特長

• ウェブ検索：SearXNG を使用し、パラメーターをカスタマイズしてウェブ検索を実行します
• ファイルシステム操作：セキュリティ制御のもとでファイルの読み取り、書き込み、管理を行います
• 拡張可能なアーキテクチャ：MCP プロトコルに準拠したカスタムツールを追加できます
• Docker のサポート：Docker と docker-compose による簡単なデプロイが可能です
• コマンドラインインターフェース：CLI による簡単な管理が可能です
• リソースとプロンプト：リソースとプロンプトに関する MCP 仕様を完全にサポートします

要件

• Python 3.13（必須）
• MCP SDK ≥ 1.6.0
• 依存関係管理用の UV パッケージマネージャー
• Docker（任意。コンテナー化デプロイ用）

実装方法

このプロジェクトでは、MCP サーバーを実装するための 2 つの方法を紹介しています。

1. FastMCP デコレーター方式（推奨）

mcp_server/server.py で FastMCP デコレーターを使用する、簡略化された方法です。

from mcp.server.fastmcp import FastMCP

# Create server
mcp = FastMCP("MCP Server")

# Add a tool using decorator
@mcp.tool()
def search(query: str, num_results: int = 5) -> dict:
    """Search the web"""
    # Implementation...
    return results

# Add a resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a greeting"""
    return f"Hello, {name}!"

# Add a prompt
@mcp.prompt()
def search_prompt(query: str) -> str:
    """Create a search prompt"""
    return f"Please search for: {query}"

2. 従来のアーキテクチャ（上級者向け）

mcp_server/core/ にある従来のアーキテクチャでは、次の要素を含む、より複雑な実装を提供しています。

• ツール登録を管理する ToolRegistry
• ツール実装用の抽象基底クラス MCPTool
• サーバー管理用のシングルトン MCPServer

この方法は複雑なアプリケーションでより柔軟に対応できますが、定型コードが多く必要です。

ツール

search

フィルターをカスタマイズして、SearXNG 経由でウェブ検索を実行します。

入力：

• query（string）：検索語
• num_results（number、任意）：返す検索結果の数（デフォルト：5、最大：20）
• language（string、任意）：検索結果の言語コード（例：「en」、「fr」）
• time_range（string、任意）：検索結果の対象期間（day、week、month、year）
• search_category（string、任意）：検索対象のカテゴリ（general、images、news、videos）

filesystem

セキュアなアクセス制御のもとで、ファイルの読み取り、書き込み、管理を行います。

操作：

• ファイルの読み取り

  • path（string）：読み取るファイルのパス
  • encoding（string、任意）：使用するエンコーディング（デフォルト：「utf-8」）
  • binary（boolean、任意）：バイナリモードで読み取るかどうか（デフォルト：false）

• ファイルの書き込み

  • path（string）：ファイルを書き込むパス
  • content（string）：書き込む内容
  • encoding（string、任意）：使用するエンコーディング（デフォルト：「utf-8」）
  • binary（boolean、任意）：バイナリモードで書き込むかどうか（デフォルト：false）
  • append（boolean、任意）：ファイルに追記するかどうか（デフォルト：false）

• ファイル一覧

  • path（string、任意）：一覧表示するディレクトリ（デフォルト：現在のディレクトリ）
  • recursive（boolean、任意）：再帰的に一覧表示するかどうか（デフォルト：false）
  • pattern（string、任意）：ファイル名に一致させるパターン

設定

環境変数

環境変数を使用して MCP サーバーを設定します。

# Server settings
MCP_SERVER__HOST=0.0.0.0
MCP_SERVER__PORT=8000

# SearXNG settings
MCP_SEARXNG__INSTANCE_URL=http://localhost:8080
MCP_SEARXNG__TIMEOUT=5

# Logging settings
MCP_LOG__LEVEL=INFO

# Data directory
MCP_DATA_DIR=./data

Claude Desktop での使用方法

オプション 1：シンプルなサンプルサーバーをインストールする

# Install the simple example server directly
mcp install examples/server.py

# Or test with the MCP Inspector
mcp dev examples/server.py

オプション 2：Docker の設定

claude_desktop_config.json に次の内容を追加します。

{
  "mcpServers": {
    "mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e",
        "MCP_SEARXNG__INSTANCE_URL=http://host.docker.internal:8080",
        "mcp-server"
      ]
    }
  }
}

SearXNG インスタンスを別途実行する必要があります。

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8080:8080",
        "-e", 
        "BASE_URL=http://localhost:8080/",
        "searxng/searxng"
      ]
    }
  }
}

インストール

Docker（推奨）

# Build the Docker image
docker build -t mcp-server .

# Run the server and SearXNG
docker-compose up

直接インストール

# Ensure you have Python 3.13 installed
python --version  # Should show Python 3.13.x

# Install uv if you don't have it
pip install uv

# Create a virtual environment and install dependencies
uv venv --python=python3.13
uv install

# Run the server
python -m mcp_server start

クライアントの例

クライアントの例については、examples/ ディレクトリを参照してください。

• examples/client.py：ClientSession API を使用する最新のクライアント
• examples/simple_client.py：API を直接呼び出すシンプルなクライアント

カスタムツールによる拡張

FastMCP 方式を使用する場合

from mcp_server.server import mcp

@mcp.tool()
def my_custom_tool(param1: str, param2: int = 10) -> dict:
    """My custom tool description"""
    # Implement tool functionality
    return {"result": f"Processed {param1} with {param2}"}

従来のアーキテクチャを使用する場合

従来のアーキテクチャでカスタムツールを追加する方法については、開発者ガイドを参照してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。

謝辞

• プロトコル仕様を提供する Model Context Protocol
• 検索エンジン機能を提供する SearXNG

プロジェクトを実行するコマンド

python -m mcp_server start --config config.env