Mammoth Analytics

mammoth-mcp-server

Mammoth MCP サーバーです。AI クライアント（Claude、ChatGPT）はそのツールを使って、サインイン中のユーザーとして Mammoth のデータを探索、クリーンアップ、変換、エクスポートします。

このサーバーが依存する Mammoth パッケージは、SDK（mammoth-io）のみです。各ツールは SDK と同様に、API 経由で Mammoth にアクセスします。サーバーはバックエンドのコードをインポートしません。

ホスト型またはローカル

• ホスト型： Mammoth はこのサーバーを https://mcp.mammoth.io/mcp で実行します。その URL を MCP クライアントに追加し、Mammoth アカウントでサインインします（OAuth）。インストールは不要です。
• ローカル： pip install mammoth-mcp-server を実行し、MCP_ENCRYPTION_KEY を設定してから mammoth-mcp-server を起動します（下記の仮想環境から実行を参照）。MCP_ENCRYPTION_KEY は、URL セーフな Base64 でエンコードされた 32 バイトの Fernet キーである必要があります。python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" で生成できます。このキーが設定されていない場合、または値が Fernet キーでない場合、サーバーは起動を拒否します。

構成

パス	内容
mammoth_mcp_server/tools/	ツールです。分野ごとに 1 つのモジュールがあります（ビュー、パイプライン、ファイル、ダッシュボードなど）。
mammoth_mcp_server/sdk.py	ツール呼び出しに渡される SDK クライアントと、モデルが扱える表現の API エラーです。
mammoth_mcp_server/jobs.py	API のルートが開始したジョブを待機します。
mammoth_mcp_server/task_params.py	変換を、API が受け取るパイプラインタスクに対応付けます。
mammoth_mcp_server/tokens.py	呼び出し元のトークンを検証します。Mammoth がトークンの有効性と対象サーバーを判定します。
mammoth_mcp_server/store.py	Redis 内の短期間有効なレコード（アップロードチケット）です。
mammoth_mcp_server/upload_routes.py	ユーザーがローカルファイルをドロップするページです。
mammoth_mcp_server/server_card.py	/.well-known/mcp/server-card.json にある公開サーバーカードです。
mammoth_mcp_server/shape.py	読み取りツールがモデルに渡す、API の応答から切り出したデータです。
mammoth_mcp_server/app.py	ASGI アプリと main() です。
mammoth_mcp_server/config.py	環境変数から読み込む、すべてのデプロイ設定です。

設定

変数	デフォルト	意味
MCP_SERVER_URL	https://mcp.mammoth.io	クライアントがアクセスするこのサーバーの URL です。
MAMMOTH_APP_URL	https://app.mammoth.io	ツールがユーザーに提示するリンクの Web アプリです。
MAMMOTH_DASHBOARD_URL	MAMMOTH_APP_URL	公開済みダッシュボードを提供するホストです。
MAMMOTH_API_URL	MAMMOTH_APP_URL + /api/v2	すべてのツール呼び出しがアクセスする API です。
MAMMOTH_API_ROOT	/api/v2	API が提供されるパスです。API に直接アクセスする場合は空に設定します。
MAMMOTH_OAUTH_URL	MAMMOTH_APP_URL + /api/v2	Mammoth の認可サーバー（発行者）であり、クライアントがユーザーをサインインさせる場所です。
MCP_REDIS_URL	redis://localhost:6379/0	アップロードチケットの保存先です。
MCP_ENCRYPTION_KEY	なし	Fernet キーです。アップロードチケット内の呼び出し元のトークンを、このキーで暗号化します。必須です。
MCP_STORE_PREFIX	mammoth_mcp	共有 Redis 内で、このデプロイメントのレコードを分離します。
MCP_HOST、MCP_PORT	127.0.0.1、8270	サーバーがリッスンする場所です。

サインイン

このサーバーは誰のサインインも処理しません。処理するのは Mammoth 独自の認可サーバー、つまり Mammoth API が提供する OAuth サーバーです。このサーバーは OAuth リソースサーバーとしてのみ動作します。

1. クライアントがトークンなしで /mcp を呼び出します。サーバーは 401 を返し、/.well-known/oauth-protected-resource/mcp を案内します。
2. そのドキュメントには Mammoth の認可サーバー（MAMMOTH_OAUTH_URL）が記載されています。クライアントはそこでサーバーのメタデータを読み取り、ユーザーをそのサーバーに誘導します。
3. ユーザーは Mammoth にサインインし、ワークスペースとプロジェクトを選んで承認します。クライアントはこのサーバーの URI <MCP_SERVER_URL>/mcp 用のトークンを要求します（resource パラメーター、RFC 8707）。
4. クライアントはそのトークンを使って /mcp を呼び出します。リクエストごとにサーバーは Mammoth にトークンの用途を問い合わせます（GET /workspaces/current）。Mammoth がトークンは有効で、このサーバーの URI 用に発行されたと返した場合に限り、サーバーはそのトークンを受け入れます。
5. 各ツール呼び出しは同じトークンを使って Mammoth API に送信されるため、ユーザーの権限が適用されます。

トークンは1つのワークスペースに属します。別のワークスペースに対するツール呼び出しは拒否されます。Workspace settings で手動作成した Mammoth API トークンは、どのサーバー用にも発行されていないため、このサーバーは拒否します。

サーバーはサインイン情報もトークンも保持しません。ただし、アップロードリンクだけは例外で、ユーザーがアップロードするか30分が経過するまで、呼び出し元のトークンを暗号化して Redis に保持します。

Mammoth に必要な設定

• MCP サーバーの URI <MCP_SERVER_URL>/mcp を、mvc-service の const.ini の [oauth] セクションにある MCP_RESOURCES に設定します。Mammoth は他のリソース用のトークンを発行しません。
• GET /workspaces/current は、ワークスペースの id とともにトークンの resource を返す必要があります。そうでなければ、このサーバーはすべてのトークンを拒否します。

環境で動作させる前にには、確認すべきすべての手順を順番に記載しています。

実行

ホスト側に必要なのが Docker だけのコンテナーとして実行

イメージはこのリポジトリからビルドされるため、デプロイ時に SDK のリリースを待つ必要はありません。ビルドコンテキストであるリポジトリのルートからビルドします。

cp mammoth-mcp-server/deploy/.dockerignore.example .dockerignore
docker build -f mammoth-mcp-server/deploy/Dockerfile -t mammoth-mcp-server .
docker run --env-file mammoth-mcp-server/deploy/.env -p 8270:8270 mammoth-mcp-server

専用の Redis とともに、1つのスタックとして実行します。

cp mammoth-mcp-server/.env.example mammoth-mcp-server/deploy/.env   # then set the values
docker compose -f mammoth-mcp-server/deploy/compose.yaml up -d --build

サーバーはリクエスト間でメモリに何も保持しないため、コンテナーを追加してスケールできます。共有するのは Redis だけです。

仮想環境から実行

pip install mammoth-mcp-server
cp .env.example .env        # then set the values
mammoth-mcp-server          # or: uvicorn mammoth_mcp_server.app:create_app --factory

deploy/ の内容

ファイル	用途
Dockerfile	このリポジトリからビルドするイメージ
compose.yaml	サーバーと Redis をまとめた1つのスタック
.dockerignore.example	ビルド前にリポジトリのルートにコピーします
mammoth-mcp-server-container.service.example	コンテナーを実行する systemd 設定
mammoth-mcp-server.service.example	仮想環境を実行する systemd 設定
nginx.example.conf	デプロイに必要な2つのサーバーブロック

環境で動作させる前に

これらの項目は、それぞれ単独でサインインを妨げます。順番に確認してください。

1. DNS とフロントエンドで、MCP_SERVER_URL をサーバーのポートに向けます。 サーバーブロックは deploy/nginx.example.conf にあります。

2. MCP_ENCRYPTION_KEY を設定します。 このサーバーが保持する唯一のシークレットです。 デフォルト値がなく、ほかに必要な設定はありません。設定を参照してください。

3. Mammoth にこのサーバーを登録します。 mvc-service の const.ini の [oauth] セクションで、MCP_RESOURCES = <MCP_SERVER_URL>/mcp と設定します。Mammoth は他のリソース用のトークンを発行しません。

4. Mammoth のホストが、クライアントが参照する場所で OAuth メタデータを提供していることを確認します。 パスを含む発行者の場合、RFC 8414 ではドキュメントが /.well-known/oauth-authorization-server/api/v2 に配置されます。apiv2 は独自のパスで提供されるため、フロントエンドでこの2つを結合する必要があります。deploy/nginx.example.conf の2つ目のサーバーブロックがこれを行います。次のコマンドで確認します。

   curl https://<mammoth host>/.well-known/oauth-authorization-server/api/v2
   

   404 ではなく、ドキュメントが返される必要があります。

5. Web アプリの OAuth 同意ページをデプロイします。 デプロイされていないと、ユーザーは存在しないページに移動し、何も承認できません。

その後、クライアントは <MCP_SERVER_URL>/mcp に接続し、ユーザーは Mammoth にサインインしてワークスペースとプロジェクトを選びます。

テスト

cd mammoth-mcp-server
python -m pytest tests -q

テストではサーバーに接続しません。SDK クライアントとツールは実物を使用し、クライアント側の HTTP トランスポートのみを置き換えます。