1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Code から Qiita に投稿できる MCP サーバーを自作した(書き込みは既定で dry-run)

1
Last updated at Posted at 2026-11-13

Qiita の記事は、手元の Obsidian で Claude Code と一緒に書いています。書き上げたあとの投稿まで Claude Code から済ませたい。そこで、Qiita API v2 を操作する MCP サーバーを Node.js で作りました。

ただ、AI に投稿や削除を任せるなら、下書きのつもりが全体公開されていた、記事を消された、という事故は避けたいところです。なので「書き込みは既定で送信しない」「投稿は既定で限定共有」を設計の真ん中に置きました。

この記事では、作ったものの全体像、安全側に倒すための工夫、実際に記事を投稿して公開するまでの流れを紹介します。ソースコードは公開していないので、要所だけ抜粋して載せます。

作ったもの

stdio で動く MCP サーバーです。ツールは 19 個(読み取り 11・書き込み 8)あります。

種類 ツール 内容
読み取り qiita_search_items 記事の検索(tag: user: stocks:> などの検索オプションが使える)
読み取り qiita_get_item 記事 1 件を Markdown の本文つきで取得。長い本文は区切って読む
読み取り qiita_list_item_comments 記事のコメント一覧
読み取り qiita_get_authenticated_user / qiita_list_my_items 自分の情報・自分の記事(限定共有と閲覧数も見える)
読み取り qiita_get_user / qiita_list_user_items / qiita_list_user_stocks ユーザー情報・記事・ストック
読み取り qiita_list_tags / qiita_get_tag / qiita_list_tag_items タグ一覧・タグ情報・タグの記事
書き込み qiita_create_item 記事の投稿
書き込み qiita_update_item 記事の更新(本文の部分置換に対応)
書き込み qiita_delete_item 記事の削除
書き込み qiita_create_comment / qiita_update_comment / qiita_delete_comment コメントの投稿・更新・削除
書き込み qiita_stock_item / qiita_unstock_item ストックする・外す

Claude Code からは、たとえば次のように頼めます。

  • 「Qiita で MCP タグのストックが多い記事を 5 件探して」
  • 「自分の記事を閲覧数の多い順に並べて」
  • 「この下書きを限定共有で Qiita に投稿して」
  • 「自分の記事の『旧バージョン』を『新バージョン』に直して」

構成

部品 中身
ランタイム Node.js 20 以上(ESM・ビルドなし。開発機は 24.22.1)
依存パッケージ @modelcontextprotocol/sdk 1.32.2、zod 4.6.7 の 2 つだけ
HTTP Node.js 標準の fetch

ファイルは 4 つに分けました。

ファイル 役割
src/index.js 起動処理(stdio)。ログは標準エラーに出す
src/qiita-client.js Qiita API v2 の呼び出し・エラー・利用制限ヘッダの読み取り
src/tools.js MCP ツールの定義
src/format.js レスポンスを AI が読みやすい形に整える

安全側に倒すための 5 つの仕掛け

書き込みの事故を防ぐ仕掛けを、何重かに重ねています。

  1. 書き込み系ツールはすべて dry_run: true が既定。送る内容を返すだけで、Qiita には送信しない
  2. 記事の投稿は既定で限定共有(private: true)。全体公開は private: false を明示したときだけ
  3. Claude Code の permissions.ask に書き込み系 8 ツールを入れ、実行の前に必ず確認ダイアログが出るようにした
  4. 環境変数 QIITA_READ_ONLY=1 で起動すると、書き込み系ツールそのものを登録しない
  5. MCP サーバーの instructions で、AI に「dry-run の結果を見せて了承を得てから送信」と伝える

1. dry-run を既定にする

zod のスキーマで dry_run の既定値を true にしています。説明文にも「ユーザーが了承したら false で実行する」と書いておくと、AI はその手順に沿って動いてくれます。

const dryRun = z
  .boolean()
  .default(true)
  .describe("true(既定)は送信せず、送る内容だけ返す。ユーザーが内容を確認して了承したら false で実行する");

投稿ツールの dry-run では、送る予定の内容を返します。本文は長いので、先頭 400 文字と全体の文字数だけにしています。

if (dry_run) {
  return {
    dry_run: true,
    action: `記事を${isPrivate ? "限定共有で" : "全体公開で"}投稿`,
    request: { method: "POST", path: "/items" },
    payload: { ...payload, body: preview(body) },  // 本文は先頭だけ
    body_length: body.length,
    warning: tokenWarning(),  // トークンが無ければ「送信できません」と先に伝える
    note: dryRunNote,
  };
}
requireToken(client);
const res = await client.post("/items", payload);

削除・コメント・ストックの dry-run では、対象の記事を実際に GET してタイトルや URL を返します。ID を間違えていても、送信の前に「消そうとしているのはこの記事です」と分かります。

2. 限定共有を既定にする

private: z.boolean().default(true).describe("true(既定)で限定共有、false で全体公開"),

「投稿して」とだけ頼んだときは限定共有になります。全体公開は、自分の目で見てから切り替える運用にしました。

3. Claude Code の確認ダイアログ

プロジェクトの .claude/settings.json で、書き込み系のツールを permissions.ask に入れています。dry-run を飛ばして dry_run: false で呼ばれても、ここで止められます。

{
  "permissions": {
    "ask": [
      "mcp__qiita__qiita_create_item",
      "mcp__qiita__qiita_update_item",
      "mcp__qiita__qiita_delete_item",
      "mcp__qiita__qiita_create_comment",
      "mcp__qiita__qiita_update_comment",
      "mcp__qiita__qiita_delete_comment",
      "mcp__qiita__qiita_stock_item",
      "mcp__qiita__qiita_unstock_item"
    ]
  }
}

4. 読み取り専用モード

調べ物だけに使いたいときは、書き込み系をそもそも見せないほうが安心です。registerTools の途中で return しているだけの単純な作りです。

export function registerTools(server, client, { readOnly = false } = {}) {
  // 読み取り系を登録
  // ...

  if (readOnly) return;

  // 書き込み系(既定は dry-run)
  // ...
}

5. サーバーの instructions で手順を伝える

MCP サーバーは、接続したクライアントに使い方の説明(instructions)を渡せます。ツールの説明文と合わせて、AI が毎回同じ手順を踏むようにしています。

const server = new McpServer(
  { name: "qiita", version: VERSION },
  {
    instructions: [
      "Qiita API v2 を操作するサーバーです。",
      "投稿・更新・削除・コメント・ストックは既定で dry-run(送信しない)です。dry-run の結果をユーザーに見せ、了承を得てから dry_run: false で実行してください。",
      "記事の投稿は既定で限定共有(private: true)です。全体公開はユーザーが明示したときだけ private: false にしてください。",
    ].join("\n"),
  },
);

使い勝手のための工夫

記事の更新は「指定した項目だけ」変える

更新ツールは、まず今の記事を GET し、指定しなかった項目は今の値で埋めてから PATCH します。「公開設定だけ変えて」と頼んだときに、AI が本文やタグを送り直す必要がありません。

dry-run では、変わる項目だけを before / after で返します。何も変わらないときはエラーにして、無駄な更新を防ぎます。

const changes = {};
if (payload.title !== cur.title) changes.title = { before: cur.title, after: payload.title };
if (newBody !== cur.body) {
  changes.body = { before_length: cur.body.length, after_length: newBody.length };
}
for (const key of ["private", "coediting", "organization_url_name", "slide"]) {
  if (args[key] !== undefined && args[key] !== cur[key]) changes[key] = { before: cur[key], after: args[key] };
}
if (Object.keys(changes).length === 0) throw new Error("変更点がありません。今の内容と同じです。");

本文の一部だけ直す replacements

2 万文字の記事で誤字を 1 つ直すたびに、全文を送り直すのは無駄です。そこで、置換元と置換後の組を渡せるようにしました。置換元が本文に無い、または複数あるときは、黙って置換せずにエラーにします。

export function applyReplacements(body, replacements) {
  let out = body;
  for (const [i, r] of replacements.entries()) {
    const count = out.split(r.find).length - 1;
    if (count === 0) throw new Error(`replacements[${i}]: 置換元の文字列が本文に見つかりません: ${preview(r.find, 80)}`);
    if (count > 1 && !r.all) {
      throw new Error(`replacements[${i}]: 置換元が本文に ${count} 箇所あります。前後を含めて一意にするか、all: true を指定してください。`);
    }
    // 置換後の文字列に $& などが入っていても特殊扱いされないよう、関数で渡す
    out = r.all ? out.split(r.find).join(r.replace) : out.replace(r.find, () => r.replace);
  }
  return out;
}

String.prototype.replace に文字列をそのまま渡すと、$& や $1 が特殊な意味を持ちます。コード例を含む技術記事ではこれが入りがちなので、置換後は関数で返すようにしました。

AI が読みやすいようにレスポンスを小さくする

Qiita API の記事のレスポンスには、Markdown の本文(body)と HTML に変換した本文(rendered_body)の両方が入っています。中身は同じなので、rendered_body は返さないようにしました。

長い記事は body_max_chars(既定 2 万文字)で区切り、続きは next_body_offset から読めるようにしています。記事 ID の代わりに記事の URL を渡しても動きます。

export function normalizeItemId(input) {
  const s = String(input).trim();
  const fromUrl = s.match(/\/items\/([0-9a-zA-Z]+)/);
  return fromUrl ? fromUrl[1] : s;
}

エラーに次の一手を添える

Qiita API のエラーメッセージに、ステータスごとのヒントを足しています。AI がユーザーに何を確かめればいいか伝えやすくなります。

ステータス 添えるヒント
401 トークンが未設定か無効。環境変数 QIITA_ACCESS_TOKEN を確認する
403 書き込みには write_qiita スコープが必要。他人の記事・コメントは変えられない
404 ID を確認する。限定共有記事の取得にはトークンが必要
429 利用制限(認証あり 1000 回/時・なし 60 回/時)。回復する時刻も添える

利用制限は、レスポンスヘッダの Rate-Limit / Rate-Remaining / Rate-Reset を読んで、毎回の結果に rate として付けています。一覧系は Total-Count と Link ヘッダから、全件数と次のページ番号も返します。

ハマりどころ: 標準出力に何も書かない

stdio の MCP サーバーでは、標準出力は MCP の通信そのものです。ここに console.log でログを出すと、クライアントは壊れたメッセージを受け取ることになります。ログは必ず標準エラーに出します。

await server.connect(new StdioServerTransport());
// console.log ではなく console.error
console.error(`[qiita-mcp] 起動しました(v${VERSION}・トークン${client.hasToken ? "あり" : "なし"})`);

Claude Code への登録

プロジェクトの .mcp.json に登録しました。トークンはファイルに書かず、環境変数から渡します。

{
  "mcpServers": {
    "qiita": {
      "command": "node",
      "args": ["path/to/qiita-mcp/src/index.js"],
      "env": {
        "QIITA_ACCESS_TOKEN": "${QIITA_ACCESS_TOKEN:-}",
        "QIITA_READ_ONLY": "${QIITA_READ_ONLY:-}"
      }
    }
  }
}

${QIITA_ACCESS_TOKEN:-} のように既定値を空にしておくと、環境変数が無い PC でもサーバーは起動します。その場合は読み取りだけ(60 回/時)で動きます。

トークンは Qiita の「設定 → アプリケーション」で個人用アクセストークンを発行します。スコープは read_qiita と、投稿もするなら write_qiita です。

# Windows(設定後に VS Code やターミナルを開き直す)
setx QIITA_ACCESS_TOKEN "発行したトークン"
# Mac(~/.zshrc に追記して開き直す)
export QIITA_ACCESS_TOKEN="発行したトークン"

テスト

本物の Qiita に書き込むテストは書きたくありません。そこで、クライアントに fetch を差し替えられる口を作りました。

constructor({ token, baseUrl, fetchImpl, timeoutMs } = {}) {
  this.token = token?.trim() || undefined;
  this.baseUrl = (baseUrl?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
  this.fetchImpl = fetchImpl ?? globalThis.fetch;  // テストでは偽の fetch を渡す
  this.timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
}

単体テストは Node.js 標準の node:test で 11 件です。「投稿は既定で dry-run かつ限定共有」「トークンが無いと送信しない」「部分置換」「同じ内容の更新はエラー」などを、Qiita には一切送らずに確かめています。

npm test        # fetch を差し替えた単体テスト(Qiita には送らない)
npm run smoke   # 本物の API に読み取りだけ投げる。書き込みは dry-run でしか呼ばない

npm run smoke は、SDK のクライアントでサーバーを実際に stdio 起動し、ツール一覧の取得・検索・記事取得・タグ取得・投稿の dry-run を順に呼ぶスクリプトです。

実際に使ってみた

完成したその日に、Claude Fable 5.2 のリリースまとめ記事をこのサーバーで投稿しました。流れは次のとおりです。

  1. Obsidian で記事を書く(Claude Code と一緒に)
  2. 「投稿までして」と頼む → qiita_get_authenticated_user でトークンを確認
  3. qiita_create_item で限定共有として投稿(Claude Code の確認ダイアログで承認)
  4. Qiita の画面で見た目を確かめる
  5. 「公開して OK」と伝える → qiita_update_item に private: false だけを渡して全体公開に切り替え

本文は約 2 万文字ありましたが、投稿は 1 回で通りました。公開への切り替えでは、本文とタグを送り直さずに private だけが変わったことを changes で確かめられました。

"changes": {
  "private": { "before": true, "after": false }
}

投稿した記事はこちらです。

既知の制約

  • 画像のアップロードはできない。Qiita API v2 に画像アップロードの API が無いため。本文中の画像 URL はそのまま使える
  • 一覧・検索は最大 100 ページ・1 ページ最大 100 件(API の上限)
  • 本物の Qiita で試したのは、読み取り・投稿・更新(公開設定の切り替え)まで。削除・コメント・ストックは単体テストでしか確かめていない

まとめ

Qiita API v2 の呼び出し自体は、fetch の薄いラッパーで足ります。工夫の大半は、AI に書き込みをさせても事故にならないようにする部分です。

  • 書き込みは既定で dry-run、投稿は既定で限定共有
  • Claude Code の permissions.ask で、送信の前に必ず人が承認する
  • 更新は指定した項目だけ変え、変更点を before / after で見せる

この 3 つを重ねたうえで、「投稿までして」と頼めるようにしました。執筆から投稿・公開まで、エディタから離れずに済みます。

参考

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?