yuna0x0-hackmd-mcp

HackMD MCP サーバー

HackMD APIと連携するModel Context Protocol（MCP）サーバーです。LLM クライアントから HackMD のノート、チーム、ユーザープロフィール、履歴データにアクセスして操作できます。

機能

• ユーザープロフィール情報の取得
• ノートの作成、読み取り、更新、削除
• チームノートの管理とチームメンバーとの共同作業
• 閲覧履歴へのアクセス
• チームの一覧表示と管理
• 2種類のトランスポートに対応：HTTP と STDIO の両方に対応
• クラウドへのデプロイに対応：Smithery などのプラットフォームに対応

要件

• Node.js 18+

ローカルインストール（STDIO トランスポート）

1. このサーバーを mcp.json / claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

別の HackMD API エンドポイントを使用する必要がある場合は、任意で HACKMD_API_URL 環境変数を設定することもできます。

2. MCP クライアント（例：Claude Desktop）を再起動します
3. ツールを使って HackMD を操作します

サーバーのデプロイ（HTTP トランスポート）

セルフホスト

ローカル開発の手順に従ってプロジェクトをローカルにセットアップし、次を実行します：

pnpm run start:http

デフォルトでは、サーバーはポート 8081 で起動します。PORT 環境変数を設定すると、ポートを変更できます。

クラウドへのデプロイ

Node.js サーバーアプリケーションに対応する任意のクラウドプラットフォームに、この MCP サーバーをデプロイできます。

Smitheryなどの MCP プラットフォーム経由でデプロイすることもできます。

設定

環境変数（STDIO トランスポート、およびホスト側で設定を指定する HTTP トランスポートサーバー）

STDIO トランスポートを使用する場合、または HTTP トランスポートサーバーをホストする場合は、環境変数を使って設定を指定できます：

• HACKMD_API_TOKEN：HackMD API トークン（すべての操作で必須）
• HACKMD_API_URL：（任意）HackMD API URL（デフォルトは https://api.hackmd.io/v1）

HTTP トランスポートサーバーにのみ適用される環境変数：

• ALLOWED_HACKMD_API_URLS：（任意）許可する HackMD API URL のカンマ区切りリストです。指定された HackMD API URL がこのリストに含まれていない場合、サーバーはリクエストを拒否します。設定されていない場合、デフォルト URL（https://api.hackmd.io/v1）のみが許可されます。

注意

トークンを事前に設定した状態で HTTP トランスポートサーバーをホストする場合は、ユーザーにアクセスを許可する前に、エンドポイントを保護し、認証を実装してください。そうしないと、誰でもあなたの HackMD トークンを使って MCP サーバーにアクセスできてしまいます。

HTTP ヘッダー（ユーザーが設定を指定する HTTP トランスポート）

HTTP トランスポートを使用する場合、ユーザーは HTTP ヘッダーを使って設定を指定できます：

• Hackmd-Api-Token：HackMD API トークン（すべての操作で必須）
• Hackmd-Api-Url：（任意）HackMD API URL（デフォルトは https://api.hackmd.io/v1）

ユーザーがヘッダーでトークンを指定し、サーバーにも HACKMD_API_TOKEN が設定されている場合は、ヘッダーの値が優先されます。

HackMD API トークンの取得

API トークンを取得するには、次の手順に従います：

1. HackMD の設定に移動します。
2. 「Create API Token」をクリックします。
3. 生成されたトークンをコピーし、.env ファイルまたは環境変数で使用します。

利用可能なツール

プロフィールツール

• get_user_info：認証済みユーザーの情報を取得

チームツール

• list_teams：ユーザーがアクセスできるすべてのチームを一覧表示

履歴ツール

• get_history：ユーザーの閲覧履歴を取得

チームノートツール

• list_team_notes：チーム内のすべてのノートを一覧表示
• create_team_note：チームに新しいノートを作成
• update_team_note：チーム内の既存のノートを更新
• delete_team_note：チーム内のノートを削除

ユーザーノートツール

• list_user_notes：ユーザーが所有するすべてのノートを一覧表示
• get_note：ID でノートを取得
• create_note：新しいノートを作成
• update_note：既存のノートを更新
• delete_note：ノートを削除

使用例

基本的なノート管理

Can you help me manage my HackMD notes?

ノートの一覧表示

Please list all my notes.

新しいノートの作成

Create a new note with the title "Meeting Notes" and content:
```
# Meeting Notes

Discussion points:
- Item 1
- Item 2
```

チームでの共同作業

Show me all the teams I'm part of and list the notes in the first team.

ローカル開発

このプロジェクトでは、パッケージマネージャーとして pnpm を使用します。

リポジトリをクローンし、依存関係をインストールします。

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp
pnpm install

設定

1. サンプルをコピーして .env ファイルを作成します。

cp env.example .env

2. .env ファイルを編集し、HackMD API トークンを追加します。

HACKMD_API_TOKEN=your_api_token

MCP Inspector でのデバッグ

MCP Inspector を使用して、HackMD MCP サーバーをテストおよびデバッグできます。

npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp

# Use this instead when Local Development
pnpm run inspector

次に、表示された URL（通常は http://localhost:6274）をブラウザーで開き、MCP Inspector のインターフェースにアクセスします。そこから、以下の操作ができます。

1. 実行中の HackMD MCP サーバーに接続する
2. 利用可能なツールを確認する
3. カスタムパラメーターを指定してツールを実行する
4. レスポンスを確認する

これは、Claude Desktop のような MCP クライアントに接続する前に、設定をテストするのに特に便利です。

Docker

GitHub Container Registry からプルします。

docker pull ghcr.io/yuna0x0/hackmd-mcp

Docker ビルド（ローカル開発）：

docker build -t ghcr.io/yuna0x0/hackmd-mcp .

Docker マルチプラットフォームビルド（ローカル開発）：

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .

MCP バンドル（MCPB）

このサーバーの MCP バンドルを作成するには、次のコマンドを実行します。

pnpm run pack:mcpb

セキュリティに関する注意

この MCP サーバーは、.env ファイル、環境変数、または HTTP ヘッダーで HackMD API トークンを受け取ります。この情報は安全に保管し、バージョン管理に決してコミットしないでください。

ライセンス

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