従業員情報 MCP サーバー

サンプルの従業員情報を格納したローカル SQLite データベースを、 Model Context Protocol (MCP) サーバーとして公開します。AI エージェントから 従業員の検索・組織構造の照会ができます。

概要

• データソース: scripts/build_employees_db.py で生成する data/employees.db（サンプル36名）

• REST API などの外部依存はなく、ローカル DB のみで完結

• トランスポート: stdio（ローカル）と HTTP/SSE の両対応

MCP クライアントの設定方法・ツールの詳しい使い方は USAGE.md を参照してください。 Claude Desktop / VS Code などへの登録手順、各ツールのパラメータ、使用例をまとめています。

Related MCP server: DB MCP (HR CSV to SQLite)

提供ツール

いずれのツールも結果を整形済み JSON 文字列で返します。

データ項目（employees テーブル）

必要要件

• Python 3.10 以上

• pip

セットアップ

# 仮想環境の作成・有効化
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # Linux/Mac

# 依存関係のインストール
pip install -r requirements.txt

初回起動までの最短手順

Windows PowerShell で、リポジトリ直下から以下の順に実行します。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

# data/employees.db が無い場合のみ作成
python scripts\build_employees_db.py --db data\employees.db

# ローカル MCP クライアントから使う場合
python main.py --transport stdio

# HTTP/SSE で起動する場合
python main.py --transport sse

HTTP/SSE モードで起動した場合、MCP クライアントには http://localhost:38117/sse を登録します。.env を作成しない場合も既定値で起動できます。

環境変数ファイル（.env）の作成

設定をカスタマイズする場合は、同梱の .env.example をコピーして .env を作成し、 必要な項目を編集します（.env は Git 管理対象外です）。既定値のままで動く場合は 作成を省略しても構いません。

copy .env.example .env        # Windows (PowerShell では Copy-Item .env.example .env)
# cp .env.example .env        # Linux/Mac

設定できる項目（DB_PATH / HTTP_HOST / HTTP_PORT / LOG_LEVEL / ALLOWED_HOSTS など）の 詳細は USAGE.md を参照してください。

実行方法

2 つのモードの違い（MCP をはじめて使う方へ）

このサーバーは、AI クライアント（Claude Desktop / VS Code など）と通信する方式（トランスポート）を 2 種類から選べます。どちらもツールの機能は同じで、違いは「AI クライアントとどうつながるか」だけです。

• stdio モード: AI クライアントがこのサーバーを子プロセスとして起動し、標準入出力 （キーボード入力・画面出力に使われるパイプ）を通じて 1 対 1 で会話します。 ネットワークを一切使わないため、同じ PC 上で使うのが前提です。

• HTTP/SSE モード: このサーバーを常駐する Web サーバーとして起動しておき、AI クライアントが http://…/sse という URL 経由で接続します。ネットワーク越しに使えるため、別の PC やコンテナ からも接続でき、複数のクライアントで共有できます。

迷ったら stdio モードを選んでください。 手元の PC で Claude Desktop や VS Code から使うだけなら stdio が最も簡単です。Docker で動かしたい、1 つのサーバーを複数人や複数ツールで共有したい、 別のマシンから接続したい、といった場合に HTTP/SSE モードを選びます。

stdio モード（ローカル MCP クライアント向け）

python main.py --transport stdio

設定例は examples/mcp-config-stdio.json を参照。

HTTP/SSE モード

python main.py --transport sse

SSE エンドポイント: http://localhost:38117/sse （ホスト・ポートは環境変数 HTTP_HOST / HTTP_PORT で変更可能）

MCP クライアントの設定・使い方

MCP クライアント（Claude Desktop / VS Code など）への登録手順、各ツールの パラメータ詳細、使用例は USAGE.md にまとめています。主な内容:

• Claude Desktop への登録（stdio モード）: claude_desktop_config.json の設定例

• VS Code への登録（HTTP/SSE モード）: .vscode/mcp.json の設定例

• 各ツールのパラメータ表

• 環境変数（.env）・トラブルシューティング

設定例ファイルは examples/mcp-config-stdio.json も参照できます。

データベースの再構築

data/employees.db は同梱済みですが、サンプルデータから再構築するには:

python scripts/build_employees_db.py --db data/employees.db

スキーマ:

• employees(employee_id, first_name, last_name, email, phone, department, job_title, employment_type, office_location, hire_date, manager_id, status)

• manager_id は同テーブルの employee_id を参照する自己参照（組織構造）。

テスト

pytest tests/ -v

Docker

docker build -t employees-mcp-server .
docker run -p 48117:38117 employees-mcp-server python main.py --transport sse

SSE エンドポイントは http://localhost:48117/sse です。

※ Dockerfile の CMD は既定で stdio 起動です。HTTP/SSE で使う場合は、上記のように python main.py --transport sse を指定して起動してください。

docker compose

docker-compose.yml で SSE 起動・DB マウント済みの構成を用意しています。

docker compose up -d

• コンテナ内部ポートは 38117 固定（HTTP_PORT）、ホスト公開ポートは 48117 に マッピングしています（ports: "48117:38117"）。ホスト側からは http://localhost:48117/sse でアクセスします。公開ポートを変えたい場合は docker-compose.yml の ports の左側の番号を変更してください。

• data/employees.db は読み取り専用（:ro）でマウントされます。

ライセンス

MIT