mcp-shorturl

ShortURLMCP

AceDataCloud APIを通じてShort URL APIを利用し、URLを短縮するためのModel Context Protocol（MCP）サーバーです。

Claude、VS Code、またはMCP互換クライアントから、共有可能な短縮URLを直接作成できます。

特長

• URL短縮 - 長いURLを短く、共有可能なリンクに変換します
• 一括短縮 - 複数のURLを一度に短縮します（1回につき最大10件）
• 無料サービス - リクエストごとのクレジット消費はありません
• 有効期限のないリンク - 短縮URLは期限切れになりません
• surl.id ドメイン - 短縮URLにはすっきりした surl.id ドメインを使用します
• Bearer 認証 - トークン認証でAPIへのアクセスを保護します

ツールのリファレンス

ツール	説明
shorturl_create	長いURLから短縮URLを作成します。
shorturl_batch_create	複数の長いURLの短縮URLを1回の一括処理で作成します。
shorturl_get_usage_guide	ShortURLツールの使用方法に関する包括的なガイドを取得します。
shorturl_get_api_info	ShortURL APIサービスの情報を取得します。

接続方法：ホスト型OAuth、APIトークン、またはローカルstdio

ホスト型エンドポイントは https://shorturl.mcp.acedata.cloud/mcp です。MCPクライアントで次のいずれかの方法を選択してください。

方法	使用する場面	認証情報の設定
ホスト型OAuth	クライアントがリモートMCP OAuthに対応している	URLだけを追加し、AceDataCloudにサインインしてアクセスを承認します。クライアント設定にトークンを貼り付ける必要はありません。
ホスト型APIトークン	クライアントでOAuthを完了できない場合、または明示的な連携用認証情報が必要な場合	Authorization: Bearer … ヘッダーでAceDataCloud APIトークンを送信します。ローカルのシークレットストアまたは環境変数に保存してください。
ローカルstdio	クライアントがローカルのMCPプロセスを実行する	mcp-shorturl をインストールし、ACEDATACLOUD_API_TOKEN をそのプロセスに渡します。この場合もAceDataCloud APIを呼び出します。

ホスト型サービスはOAuthメタデータとDynamic Client Registration（DCR）を提供します。DCRはクライアントアプリケーションを登録するものであり、APIキーではありません。 OAuthでサインインすると、クライアントは取得したBearerトークンを送信します。また、アカウント用のAPI認証情報を再利用または新規作成することがあります。ブラウザーでサインインするには、引き続きAceDataCloudアカウントが必要です。ホスト型サービスは従量課金制の場合があります。実際に操作する前に、最新のサービスドキュメントと表示料金を確認してください。同じサーバーにOAuthログインと固定の Authorization ヘッダーを両方設定しないでください。

ホステッド OAuth の例

• Claude と Claude Desktop のチャット： Customize → Connectors → Add custom connector からリモートカスタムコネクターを追加し、https://shorturl.mcp.acedata.cloud/mcp を入力して、サインインを選択します。Claude から OAuth クライアントの登録方法を尋ねられた場合は、Register automatically を選択します。同意を完了します。Claude Desktop のローカルな claude_desktop_config.json は別途設定します。Claude コネクターガイド。
• Claude Code： claude mcp add --transport http --scope user shorturl https://shorturl.mcp.acedata.cloud/mcp を実行し、続けて claude mcp login shorturl を実行します。/mcp を確認します。Claude Code MCP ガイド。
• Cursor： https://shorturl.mcp.acedata.cloud/mcp のみを指定してリモートサーバーを追加します。プロジェクトで使用する場合は、以下のエントリーを <project>/.cursor/mcp.json にマージします。個人用の場合は、~/.cursor/mcp.json を使用します。Cursor MCP ガイド。
• VS Code / Copilot： MCP: Add Server を実行し、HTTP を選択して https://shorturl.mcp.acedata.cloud/mcp を入力し、ブラウザーでのサインインを完了します。新しいポータブルなワークスペース設定では <project>/.mcp.json を使用します。以下の VS Code 固有の形式では、<project>/.vscode/mcp.json またはユーザープロファイルを使用します。MCP: List Servers を確認します。VS Code の MCP セットアップ。
• Codex： codex mcp add shorturl --url https://shorturl.mcp.acedata.cloud/mcp を実行し、続けて codex mcp login shorturl を実行します。ユーザー設定は ~/.codex/config.toml にあります。Codex 公式 MCP ガイド。

Cursor プロジェクト設定（OAuth）：

{
  "mcpServers": {
    "shorturl": {"url": "https://shorturl.mcp.acedata.cloud/mcp"}
  }
}

VS Code 固有のワークスペース設定（OAuth）：

{
  "servers": {
    "shorturl": {"type": "http", "url": "https://shorturl.mcp.acedata.cloud/mcp"}
  }
}

ホステッド API トークン

1. Ace Data Cloud → Applicationsを開きます。サインインするか、先にアカウントを登録してください。
2. General applicationを探します。作成されていない場合は、Initialize General Applicationを選択します。一般キーではアカウントで利用可能なサービスを使用できますが、専用アプリケーションのキーはそのサービスに限定されます。必要なサービス／モデルへのアクセス権と現在の料金を確認してください。
3. アプリケーションカードからAPI Keyをコピーするか、Keys / Manage Keys → Createを開いて、この連携用の別のキーを作成します。個別に失効またはローテーションできるよう、識別しやすい名前を付けてください。
4. キーを作成する際は、Expiration Time、Set Usage Limitation、Allowed APIsを確認してください。必要な制限のみを有効にし、呼び出す操作を許可してから、Createをクリックし、キー一覧からトークンをコピーします。タスクの照会権限では、生成の送信は許可されません。アプリケーションの残高で最初のリクエストを処理できることを確認してください。トライアルの利用枠がある場合は、現在アカウントに表示されている内容が適用されます。
5. 引用符、空白、Bearer を含めず、トークンの値だけをコピーします。API Key／API Token フィールドにはこの生の値を入力します。手動で設定する HTTP Authorization ヘッダーの場合に限り、Bearer プレフィックスが必要です。platform-...のアカウント管理用トークンを生成 API キーの代わりに使用することはできません。

キーはクライアントの認証情報ストア、または以下に示す環境変数に保存してください。プロンプト、共有ワークフロー、スクリーンショット、Git コミットには絶対に含めないでください。認証に失敗した場合は、別のキーを作成する前に、コピーした値全体、アプリケーション／サービスへのアクセス権、有効期限、使用制限、残高を確認してください。

固定の Bearer ヘッダーは OAuth をバイパスします。ヘッダーが無効な場合は、ブラウザーでのサインインを試す前に削除してください。保存した認証情報は非公開にしてください。

Claude Code では、サーバーの追加時にシェルがトークンを展開します。保存されたユーザー MCP 設定は秘密情報として扱ってください。

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user shorturl https://shorturl.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

Claude Code のプロジェクト設定では、<project>/.mcp.jsonに変数参照を記述し、Claude Code の起動に使用する環境でその変数を設定します。

{
  "mcpServers": {
    "shorturl": {
      "type": "http",
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor では、~/.cursor/mcp.jsonまたはコミット対象外のプロジェクト設定で、異なる環境変数の構文を使用します。

{
  "mcpServers": {
    "shorturl": {
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

VS Code では、MCP: Open User Configurationを実行し、このサーバーとマスクされた入力を統合します。${input:...}は VS Code のユーザー／ワークスペース形式用であり、Agent Host の.mcp.json形式との互換性はありません。

{
  "inputs": [
    {"id": "acedata-shorturl-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "shorturl": {
      "type": "http",
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-shorturl-token}"}
    }
  }
}

Clineでは、MCP 設定 UI または CLI ファイル~/.cline/data/settings/cline_mcp_settings.jsonを使用します。リモートトランスポートの値はstreamableHttpです。JetBrains AI Assistantでは、**Settings → Tools → AI Assistant → Model Context Protocol (MCP)**からリモート URL を追加します。Zedでは、OAuth の場合は URL のみを指定するcontext_serversエントリーを使用するか、ローカルの Bearer ヘッダーを追加します。これらのクライアントは設定スキーマがそれぞれ異なるため、他のクライアントの JSON をコピーせず、現在の UI に従ってください。Cline · JetBrains · Zed.

ローカル stdio

パッケージをインストールし、ローカルプロセスに API トークンを渡します。

python -m pip install mcp-shorturl
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-shorturl

Claude Desktop のローカル MCP では、開発者設定から開くファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）にこのエントリーをマージします。uvx を使うには、uv が PATH 上に必要です。

{
  "mcpServers": {
    "shorturl": {
      "command": "uvx",
      "args": ["mcp-shorturl"],
      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
    }
  }
}

このユーザーレベルのファイルは非公開にしてください。セルフホスト可能な HTTP は mcp-shorturl --transport http --port 8000 で使用できますが、適切なネットワークおよび TLS 制御の下でのみ公開してください。ローカル実行でも AceDataCloud API が呼び出されます。

サービスを使用する前の確認

1. https://shorturl.mcp.acedata.cloud/health が {"status":"ok"} を返す場合、確認できるのはエンドポイントへの到達性のみです。
2. MCP クライアントがツールを読み込むことを確認してください。shorturl_get_usage_guide はリファレンスツールであり、下流 API へのアクセスや残高は確認しません。
3. API を完全に確認する必要がある場合は、現在のサービスドキュメントと表示されている料金を確認してから、独自の有効な入力で shorturl_create を呼び出してください。

401 が発生した場合は、クライアントが使用した認証経路と、トークンまたは OAuth セッションが有効かどうかを確認してください。403 は、アカウント権限またはコンテンツモデレーションによる失敗を示している可能性があります。返されたエラーを確認してください。残高不足や下流サービスの障害には、それぞれ個別の診断が必要です。ツールが一覧に表示されたり、タスクが送信されたりしただけでは、処理が成功したことにはなりません。

利用可能なツール

URL 短縮ツール

ツール	説明
shorturl_create	単一の URL を短縮します
shorturl_batch_create	複数の URL を一度に短縮します（最大 10 件）

情報ツール

ツール	説明
shorturl_get_usage_guide	詳細な使用ガイドを取得します
shorturl_get_api_info	API の詳細とエラーコードを取得します

使用例

単一の URL を短縮する

User: Shorten this URL: https://platform.acedata.cloud/documents/shorturl

Claude: I'll shorten that URL for you.
[Calls shorturl_create with url="https://platform.acedata.cloud/documents/shorturl"]

Result: https://surl.id/1uHCs01xa5

複数の URL を一括で短縮する

User: Shorten these URLs for my social media posts:
- https://example.com/blog/very-long-article-title-about-ai
- https://example.com/products/new-release-2024

Claude: I'll shorten both URLs at once.
[Calls shorturl_batch_create with urls=[...]]

ドキュメント用のリンクを作成する

User: I need clean short links for these reference URLs in my doc.

Claude: I'll create short links for all your references.
[Calls shorturl_batch_create with the list of URLs]

レスポンスの構造

成功レスポンス

{
  "success": true,
  "data": {
    "url": "https://surl.id/1uHCs01xa5"
  }
}

エラーレスポンス

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

設定

環境変数

変数	説明	デフォルト
ACEDATACLOUD_API_TOKEN	AceDataCloud の API トークン	必須
ACEDATACLOUD_API_BASE_URL	API のベース URL	https://api.acedata.cloud
ACEDATACLOUD_OAUTH_CLIENT_ID	OAuth クライアント ID（ホステッドモード）	—
ACEDATACLOUD_PLATFORM_BASE_URL	プラットフォームのベース URL	https://platform.acedata.cloud
SHORTURL_REQUEST_TIMEOUT	リクエストのタイムアウト時間（秒）	30
LOG_LEVEL	ログレベル	INFO

コマンドラインオプション

mcp-shorturl --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

開発

開発環境のセットアップ

# Clone repository
git clone https://github.com/AceDataCloud/ShortURLMCP.git
cd ShortURLMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

テストの実行

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest tests/test_integration.py -m integration

コード品質

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

ビルドと公開

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

プロジェクト構成

ShortURLMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for ShortURL API
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   └── server.py          # MCP server initialization
├── tools/                  # MCP tool definitions
│   ├── __init__.py
│   ├── shorturl_tools.py  # URL shortening tools
│   └── info_tools.py      # Information tools
├── prompts/                # MCP prompt templates
│   └── __init__.py
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_config.py
│   └── test_integration.py
├── deploy/                 # Deployment configs
│   ├── run.sh
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .env.example           # Environment template
├── .gitignore
├── .ruff.toml             # Ruff linter configuration
├── CHANGELOG.md
├── Dockerfile             # Docker image for HTTP mode
├── docker-compose.yaml    # Docker Compose config
├── LICENSE
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
└── README.md

API リファレンス

このサーバーは、AceDataCloud Short URL APIをラップしています。

• エンドポイント：POST /shorturl
• 入力：{ "content": "https://long-url.example.com/..." }
• 出力：{ "success": true, "data": { "url": "https://surl.id/..." } }
• 料金：無料（0 クレジット）
• 認証：Bearer トークン

API ドキュメント全文：AceDataCloud Platform

ドキュメント

ドキュメント

ライセンス

MIT License の詳細については、LICENSEを参照してください。