Skill MCP

🚀 スキル管理MCPサーバー

このModel Context Protocol (MCP) サーバーは、Claudeが ~/.skill-mcp/skills に保存されたスキルを管理できるようにします。このシステムにより、Claudeはスキルの作成、編集、実行、管理をプログラムで行うことができ、環境変数を使用したスキルスクリプトの実行も可能です。

🚀 クイックスタート

1. uvのインストール

このプロジェクトでは、高速で信頼性の高いPythonパッケージ管理ツールである uv を使用しています。

# uvのインストール（uvxを含む）
curl -LsSf https://astral.sh/uv/install.sh | sh

2. MCPクライアントの設定

MCPサーバーを設定に追加します。サーバーは、uvx を通じてPyPIから自動的にダウンロードされ、実行されます。

Claude Desktop - 設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor - 設定ファイルを編集します。

• macOS: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json
• Linux: ~/.cursor/mcp.json

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ]
    }
  }
}

これで完了です！インストールは必要ありません。uvx が自動的にPyPIから最新バージョンをダウンロードし、実行します。

3. MCPクライアントの再起動

Claude DesktopまたはCursorを再起動して、MCPサーバーを読み込みます。

4. テスト

新しい会話で以下のコマンドを入力します。

List all available skills

Claudeは、~/.skill-mcp/skills/ 内のスキルを表示するために、skill-mcpツールを使用するはずです。

✨ 主な機能

スキル管理

• ✅ 利用可能なすべてのスキルをリスト表示
• ✅ スキルファイルとディレクトリ構造を閲覧
• ✅ スキルファイル（SKILL.md、スクリプト、リファレンス、アセット）を読み取り
• ✅ 新しいスキルファイルとディレクトリを作成
• ✅ 既存のスキルファイルを更新
• ✅ スキルファイルを削除

スクリプト実行

• ✅ Python、Bash、その他の実行可能スクリプトを実行
• ✅ Pythonスクリプトの自動依存関係管理（uvインラインメタデータ（PEP 723）を使用）
• ✅ シークレットからの自動環境変数注入
• ✅ コマンドライン引数のサポート
• ✅ カスタム作業ディレクトリのサポート
• ✅ 標準出力と標準エラー出力のキャプチャ
• ✅ 安全のための30秒タイムアウト

直接Python実行 - 複数スキルの統合 🚀

• ✅ 一度の実行で複数のスキルを統合 - 異なるスキルのユーティリティをシームレスに組み合わせる
• ✅ スクリプトファイルを作成せずに直接Pythonコードを実行
• ✅ クロススキルインポート - 任意のスキルからモジュールを再利用可能なライブラリとしてインポート
• ✅ 自動依存関係集約 - すべてのインポートされたスキルの依存関係が自動的にマージされる
• ✅ 環境変数の読み込み - すべての参照されたスキルの.envファイルが自動的に読み込まれる
• ✅ PEP 723サポート - コード内のインライン依存関係宣言
• ✅ 98.7% 効率的 - 拡張可能なエージェントに適したAnthropicの推奨MCPパターンに従う
• ✅ 多スキルワークフロー、迅速な実験、データ分析、複雑なパイプラインに最適

環境変数

• ✅ 環境変数のキーをリスト表示（安全のため値は表示されない）
• ✅ スキルごとに環境変数を設定または更新
• ✅ スキルごとの .env ファイルに永続的に保存
• ✅ スクリプト実行時に自動的に注入

📦 インストール

PyPIからのインストール

パッケージをグローバルにインストールするには（オプション）：

pip install skill-mcp

または、インストールせずに uvx を使用して実行することをおすすめします。

uvx --from skill-mcp skill-mcp-server

開発環境のセットアップ

貢献する場合やソースから実行する場合は、以下の手順を実行します。

# リポジトリをクローン
git clone https://github.com/fkesheh/skill-mcp.git
cd skill-mcp

# 依存関係をインストール
uv sync

# テストを実行
uv run pytest

# サーバーをローカルで実行
uv run -m skill_mcp.server

MCPクライアントの設定でローカル開発バージョンを使用するには：

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/skill-mcp",
        "-m",
        "skill_mcp.server"
      ]
    }
  }
}

💻 使用例

基本的な使用法

# 依存関係を持つシンプルなインライン実行
# /// script
# dependencies = [
#   "requests>=2.31.0",
# ]
# ///

import requests
response = requests.get("https://api.example.com/data")
print(response.json())

高度な使用法

クロススキルインポート - 複数のスキルを統合

コンポジションの力 - 一度ユーティリティスキルを作成し、無限の方法で組み合わせることができます。

実際の例：計算機、データプロセッサ、CRMスキルを統合して販売データを処理します。

ステップ1: 再利用可能なモジュールを持つ計算機スキルを作成

# calculator:math_utils.py
def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

ステップ2: データプロセッサスキルのユーティリティを作成

# data-processor:csv_parser.py
# /// script
# dependencies = ["pandas>=2.0.0"]
# ///
import pandas as pd

def parse_csv_url(url):
    return pd.read_csv(url)

def filter_by_status(df, status):
    return df[df['status'] == status]

ステップ3: 両方のスキルを一度の実行で統合！

# Execute with skill_references: ["calculator:math_utils.py", "data-processor:csv_parser.py"]
from math_utils import calculate_average
from csv_parser import parse_csv_url, filter_by_status

# 販売データを取得
sales_df = parse_csv_url('https://example.com/sales.csv')

# アクティブな取引をフィルタリング
active_deals = filter_by_status(sales_df, 'active')

# 計算機スキルを使用して平均取引サイズを計算
deal_values = active_deals['amount'].tolist()
avg_deal = calculate_average(deal_values)

print(f"Active deals: {len(active_deals)}")
print(f"Average deal size: ${avg_deal:,.2f}")

📚 詳細ドキュメント

共通のuvコマンド

このリポジトリでの開発には、以下のコマンドが使用できます。

uv sync              # 依存関係をインストール/更新
uv run python script.py   # プロジェクト環境でPythonを実行
uv add package-name  # 新しい依存関係を追加
uv pip list          # インストールされたパッケージを表示
uv run pytest tests/ -v   # テストを実行

uvは自動的に .venv/ を作成および管理するため、手動で仮想環境を作成する必要はありません！

スクリプトの依存関係 (PEP 723)

✅ run_skill_script と execute_python_code の両方がPEP 723をサポートしています！

Pythonスクリプトとコードは、uvのインラインメタデータを使用して独自の依存関係を宣言できます。サーバーはこれを自動的に検出し、uv run を使用して依存関係を処理します。

#!/usr/bin/env python3
# /// script
# dependencies = [
#   "requests>=2.31.0",
#   "pandas>=2.0.0",
# ]
# ///

import requests
import pandas as pd

# ここにあなたのスクリプトコードを記述 - 依存関係は自動的にインストールされます！
response = requests.get("https://api.example.com/data")
df = pd.DataFrame(response.json())
print(df.head())

利用可能なMCPツール

サーバーは、Claudeに以下の統合CRUDツールを提供します。

高度な設定

カスタムスキルディレクトリ

スキルディレクトリは、SKILL_MCP_DIR 環境変数を使用してカスタマイズできます。設定されていない場合、デフォルトは ~/.skill-mcp/skills です。

環境変数を使用して設定する（推奨）

# 現在のセッションで一時的に設定
export SKILL_MCP_DIR="/custom/path/to/skills"

# シェル設定ファイル（~/.bashrc、~/.zshrcなど）に永続的に設定
echo 'export SKILL_MCP_DIR="/custom/path/to/skills"' >> ~/.zshrc

MCPクライアントの設定で設定する Claude DesktopまたはCursorの場合、MCP設定に環境変数を追加します。

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ],
      "env": {
        "SKILL_MCP_DIR": "/custom/path/to/skills"
      }
    }
  }
}

アーキテクチャと実装

パッケージ構造

src/skill_mcp/
├── server.py              # MCPサーバーのエントリポイント
├── models.py              # Pydantic入力/出力モデル（下位互換性）
├── models_crud.py         # 統合CRUD入力モデル
├── core/
│   ├── config.py          # 設定定数
│   └── exceptions.py      # カスタム例外タイプ
├── services/
│   ├── env_service.py     # 環境変数CRUD
│   ├── file_service.py    # ファイルCRUD操作
│   ├── skill_service.py   # スキルの検出とメタデータ
│   ├── script_service.py  # スクリプト実行とPEP 723
│   └── template_service.py # テンプレート管理
├── utils/
│   ├── path_utils.py      # 安全なパス検証
│   ├── yaml_parser.py     # YAMLフロントマター解析
│   └── script_detector.py # スクリプト機能検出
└── tools/
    ├── skill_crud.py      # 統合スキルCRUDツール
    ├── skill_files_crud.py # 統合ファイルCRUDツール
    ├── skill_env_crud.py  # 統合環境CRUDツール
    └── script_tools.py    # スクリプト実行ツール

tests/
├── conftest.py            # Pytestフィクスチャ
└── 20+ test modules       # 145個のテスト（86%のカバレッジで合格）

🔧 技術詳細

テスト結果

単体テスト: 145/145 合格 ✅

カバレッジ: 86% (959/1120 ステートメントがカバーされています)

すべてのモジュールにわたる包括的なテストカバレッジです。

セキュリティ機能

パス検証

• すべてのファイルパスは、ディレクトリトラバーサル攻撃を防止するために検証されます。
• ".." を含むパスまたは "/" で始まるパスは拒否されます。
• すべての操作はスキルディレクトリ内に制限されます。

環境変数

• 変数の値はリスト表示時には公開されません。
• スキルごとの .env ファイルに保存されます。
• ファイルのパーミッションは制限されるべきです（各.envに対して chmod 600）。

スクリプト実行

• 30秒のタイムアウトで無限ループを防止します。
• スクリプトはユーザーの権限で実行されます（昇格された権限ではありません）。
• 出力サイズ制限でメモリ問題を防止します。
• デバッグのために標準出力と標準エラー出力の両方をキャプチャします。

📄 ライセンス

MITライセンス

Copyright (c) 2025

このソフトウェアおよび関連ドキュメントファイル（「ソフトウェア」）のコピーを取得するすべての人に対して、無料で、制限なくソフトウェアを取り扱う権利がここに与えられます。これには、使用、コピー、変更、マージ、公開、配布、サブライセンス、および/またはソフトウェアのコピーを販売する権利が含まれ、ソフトウェアが提供される人に対しても同様のことを許可することができますが、以下の条件に従う必要があります。

上記の著作権表示とこの許諾表示は、ソフトウェアのすべてのコピーまたは実質的な部分に含まれる必要があります。

ソフトウェアは「現状のまま」提供され、明示的または黙示的ないかなる保証もなく、商品性、特定の目的への適合性、および非侵害の保証を含みますが、これらに限定されません。いかなる場合も、著者または著作権者は、契約、不法行為、またはその他の方法による訴訟において、ソフトウェアまたはソフトウェアの使用またはその他の取引に関連して生じるいかなる請求、損害、またはその他の責任に対しても責任を負いません。

トラブルシューティング

"MCP server not found"

• uv がPATHに含まれていることを確認します: which uv (またはWindowsでは where uv)
• .skill-mcp ディレクトリのパスが正しく絶対パスであることを確認します。
• 依存関係をテストします: cd ~/.skill-mcp && uv run python -c "import mcp; print('OK')"
• ~/.skill-mcp/ に pyproject.toml が存在することを確認します。

"Permission denied" エラー

chmod +x ~/.skill-mcp/skill_mcp_server.py
chmod 755 ~/.skill-mcp
chmod 755 ~/.skill-mcp/skills
find ~/.skill-mcp/skills -name ".env" -exec chmod 600 {} \;

スクリプトが実行されない場合

• スクリプトに実行権限があることを確認します。
• インタープリター（python3、bash）がPATHに含まれていることを確認します。
• list_env_keys を使用して、必要な変数が設定されていることを確認します。
• run_skill_script からの標準エラー出力を確認します。

環境変数が機能しない場合

• 環境変数が設定されていることを確認します: スキルに対して read_skill_env を使用します。
• .env ファイルが存在することを確認します: cat ~/.skill-mcp/skills/<skill-name>/.env
• あなたのスクリプトが os.environ から読み取っていることを確認します。

ベストプラクティス

スキル開発

• 標準的なスキル構造（SKILL.md、scripts/、references/、assets/）に従います。
• SKILL.mdを簡潔かつ重点的に保ちます。
• 進歩的な開示を使用します（大きなドキュメントをリファレンスに分割します）。
• スクリプトを作成した直後にテストします。

環境変数

• 説明的な名前を使用します（API_KEY、DATABASE_URL）。
• 機密値をログに記録したり印刷したりしないでください。
• .env ファイルのパーミッションを設定します: chmod 600 ~/.skill-mcp/skills/<skill-name>/.env

スクリプト開発

• 意味のある終了コードを使用します（0 = 成功）。
• 役立つメッセージを標準出力に印刷します。
• エラーを標準エラー出力に印刷します。
• エラーハンドリングを含めます。
• 依存関係のあるPythonスクリプトの場合: インラインメタデータ（PEP 723）を使用します。

# /// script
# dependencies = [
#   "package-name>=version",
# ]
# ///

• メタデータのないスクリプトはシステムのPythonインタープリターを使用します。
• メタデータのあるスクリプトは、uvを通じて自動的に分離された環境を取得します。

🔐 機密情報の安全な管理

LLMがあなたの機密資格情報にアクセスするのを防ぐために：

✅ 推奨: ファイルシステム上で直接.envファイルを更新する

# スキルの.envファイルを直接編集する（LLMはあなたのローカルファイルにアクセスできない）
nano ~/.skill-mcp/skills/my-skill/.env

# シークレットを手動で追加する
API_KEY=your-actual-api-key-here
DATABASE_PASSWORD=your-password-here
OAUTH_TOKEN=your-token-here

# ファイルを安全にする
chmod 600 ~/.skill-mcp/skills/my-skill/.env

⚠️ 重要: LLM生成コードの検証

Claudeや他のLLMがこのMCPシステムを使用してスキルやスクリプトを作成または変更する場合、本番環境で実行する前に常に生成されたコードを検証してください。

セキュリティ上の考慮事項

• ⚠️ 常に生成されたコードをレビューする - LLMは間違いを犯したり、最適でないコードを生成することがあります。
• ⚠️ セキュリティ問題をチェックする - ハードコードされた資格情報、不安全な操作、または脆弱性を探します。
• ⚠️ 十分にテストする - 最初に分離された環境でスクリプトを実行します。
• ⚠️ 権限を検証する - スクリプトが適切なファイルおよびシステム権限を持っていることを確認します。
• ⚠️ 依存関係を監視する - PEP 723を通じてインストールされた外部パッケージをレビューします。

LLM生成スキルのベストプラクティス

1. 実行前にレビューする - 常に生成されたスクリプトを読み通します。
2. 分離してテストする - 本番環境で使用する前に安全な環境で実行します。
3. バージョン管理を使用する - すべての変更をgitで追跡して監査証跡を残します。
4. エラーハンドリングを実装する - 堅牢なエラーハンドリングとロギングを追加します。
5. リソース制限を設定する - タイムアウトとリソース制約を使用します。
6. 最小限の権限で実行する - スキルをrootまたは昇格された権限で実行しないでください。
7. 入力を検証する - ユーザーが提供したデータをサニタイズします。
8. 監査ログを確認する - スクリプトが実際に行うことを確認し、実行を追跡します。

一般的なチェック事項

• ❌ ハードコードされたAPIキー、パスワード、またはトークン
• ❌ 不安全なファイル操作またはパストラバーサルのリスク
• ❌ 検証されていない外部コマンドまたはシェルインジェクションのリスク
• ❌ エラーハンドリングまたはエッジケースの欠如
• ❌ 制限のないリソース集中型操作
• ❌ 不安全な逆シリアル化（eval、pickleなど）
• ❌ 過度の権限要求
• ❌ 信頼できない外部依存関係

疑問がある場合

• Claude/LLMにコードを説明してもらいます。
• 重要なコードを別の人にレビューしてもらいます。
• リンターやセキュリティスキャンツールを使用します。
• コンテナまたはVMで実行して分離します。
• 破壊的な操作の前に読み取り専用操作から始めます。

覚えておいてください: LLM生成コードは出発点です。セキュリティと信頼性のために、あなたの検証とレビューが不可欠です。

サポート

セットアップの問題や質問については、以下を参照してください。

• https://modelcontextprotocol.io のClaudeのMCPドキュメント
• https://github.com/modelcontextprotocol/python-sdk のMCP Python SDKドキュメント