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 つの仕掛け
書き込みの事故を防ぐ仕掛けを、何重かに重ねています。
- 書き込み系ツールはすべて
dry_run: trueが既定。送る内容を返すだけで、Qiita には送信しない - 記事の投稿は既定で限定共有(
private: true)。全体公開はprivate: falseを明示したときだけ - Claude Code の
permissions.askに書き込み系 8 ツールを入れ、実行の前に必ず確認ダイアログが出るようにした - 環境変数
QIITA_READ_ONLY=1で起動すると、書き込み系ツールそのものを登録しない - 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 のリリースまとめ記事をこのサーバーで投稿しました。流れは次のとおりです。
- Obsidian で記事を書く(Claude Code と一緒に)
- 「投稿までして」と頼む →
qiita_get_authenticated_userでトークンを確認 -
qiita_create_itemで限定共有として投稿(Claude Code の確認ダイアログで承認) - Qiita の画面で見た目を確かめる
- 「公開して 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 つを重ねたうえで、「投稿までして」と頼めるようにしました。執筆から投稿・公開まで、エディタから離れずに済みます。