Qiita API를 MCP로 구현했더니 Claude Code가 기사 포스팅 도구가 된 이야기

Claude Code(등 MCP 대응 클라이언트)에서 Qiita를 검색·포스팅·편집할 수 있는 비공식 MCP 서버 unofficial-qiita-mcp를 만들었기에 소개합니다.

Qiita API v2를 래핑(Wrapping)하고 있을 뿐인 심플한 것이지만, 이것을 넣어두면 "기사를 쓰는" 작업을 에디터 밖으로 내보내지 않아도 됩니다.

MCP (Model Context Protocol)는 간단히 말하면 AI 클라이언트에 외부 도구를 붙이기 위한 메커니즘입니다. 이를 사용하면 AI가 "Qiita에서 기사를 검색한다", "초안을 포스팅한다"와 같은 조작을 대화 도중에 그대로 호출할 수 있게 됩니다.

예를 들어 "Docker 태그가 붙은 인기 기사 10개를 찾아줘"라고 부탁하면 AI가 검색 도구를 호출하여 결과를 돌려주고, "이 초안을 한정 공유로 포스팅해줘"라고 말하면 그대로 기사가 만들어지는 식입니다.

상호작용의 뒷단에서 API를 호출하는 부분을 대신 처리해 주는 것이 MCP 서버라고 생각하시면 됩니다.

참고로 이 기사에서 소개하는 것은 자체 제작한 비공식 프로젝트입니다. Qiita 주식회사와는 관계가 없습니다. "Qiita"는 해당 회사의 상표이며, 본 도구는 공개된 API v2를 이용하고 있습니다.

무언가 앱을 만들고 그 소개를 Qiita에 쓰려고 하면, 에디터와 브라우저를 몇 번이고 왔다 갔다 해야 해서 다소 번거로운 부분이 있습니다. 코드를 보면서 쓰고 붙여넣고, 프리뷰를 확인하고 다시 수정하는…… 이러한 왕복 작업이 은근히 쌓이게 됩니다.

그래서 Claude Code를 사용할 수 없을까 생각했습니다. Claude Code는 프로젝트의 내용을 전부 읽을 수 있습니다. 그렇다면 기사 초안 작성까지 맡기고, 그대로 Qiita에 포스팅하는 것까지 터미널만으로 완결할 수 없을까.

그리하여 그 "포스팅하는 부분까지"를 담당하는 부분으로서 만들어 본 것이 이 MCP 서버입니다.

Qiita API v2를 한 차례 래핑하여 다음과 같은 도구를 준비했습니다. 기사의 검색·취득부터 포스팅·편집·삭제, 댓글이나 스톡(Stock)까지 일련의 조작을 커버하고 있습니다. 읽기 계열과 쓰기 계열로 나누어 소개하겠습니다.

정보를 가져오기만 할 뿐, Qiita 측에 변경을 가하지 않는 도구입니다.

도구	설명
qiita_search_items	공개 기사를 검색합니다. tag:Ruby stocks:>10와 같은 Qiita의 검색 구문을 그대로 사용할 수 있어, 태그나 인기도로 필터링할 수 있습니다.
qiita_get_item	기사 ID를 지정하여 본문을 Markdown을 포함해 통째로 가져옵니다. 편집 전에 현재 내용을 읽어오고 싶을 때 편리합니다.
qiita_get_authenticated_user	토큰에 연결된 사용자 정보를 반환합니다. 토큰이 제대로 통하는지 확인하는 통신 확인용으로 사용할 수 있습니다.
qiita_list_my_items	인증된 사용자 본인이 포스팅한 기사를 최신순으로 나열합니다.
qiita_list_item_comments	지정한 기사에 달린 댓글을 나열합니다.

검색이나 기사 취득 등 공개 기사를 대상으로 하는 도구는 토큰 없이도 동작합니다 (qiita_get_authenticated_user와 qiita_list_my_items는 자신의 정보를 다루기 때문에 토큰이 필요합니다). 단, 토큰이 없는 경우에는 레이트 리밋(Rate Limit)이 다소 엄격해집니다 (인증 시 시간당 1000회, 인증 미사용 시 시간당 60회).

이쪽은 Qiita 측에 실제로 변경을 가하는 도구입니다. 이용을 위해서는 토큰의 write_qiita 스코프(Scope)가 필요합니다.

도구	설명
qiita_create_item	새로운 기사를 게시합니다. 사고 방지를 위해 초기값은 비공개(private:true)로 설정되어 있으며, 공개하고 싶을 때만 명시적으로 private:false를 지정하는 방식입니다.
qiita_update_item	기존 기사를 업데이트합니다. 전송한 필드로 내용이 교체되므로, 먼저 qiita_get_item으로 현황을 가져온 뒤 작업하는 것이 안전합니다.
qiita_delete_item	ID를 지정하여 기사를 삭제합니다. 취소할 수 없으므로, AI에게 맡길 때는 대상 ID를 잘 확인해 주세요.
qiita_post_comment	지정한 기사에 Markdown 형식으로 댓글을 게시합니다.
qiita_stock_item / qiita_unstock_item	기사를 자신의 스톡(Stock)에 추가하거나 제거합니다.

쓰기 계열은 실제로 데이터를 변경하므로, 특히 삭제나 공개는 가이드라인을 준수하며 신중하게 다뤄주세요.

도입 과정은 클론(Clone) · 빌드(Build) · 토큰 발행 · 등록 순서로 진행됩니다. 순서대로 살펴보겠습니다. 실행하려면 Node.js가 필요합니다 (본인 환경에서는 v24에서 동작을 확인했습니다).

먼저 GitHub에서 소스를 가져와 의존성을 설치하고 빌드합니다. 빌드가 성공하면 엔트리 포인트(Entry point)인 dist/index.js가 생성됩니다.

git clone https://github.com/kaze-uta/unofficial-qiita-mcp.git
cd unofficial-qiita-mcp
npm install
...

Qiita 설정 화면에서 개인용 액세스 토큰(Personal Access Token)을 발행합니다. 스코프(Scope)는 용도에 따라 선택합니다.

• 검색이나 가져오기 등 읽기 전용이라면 read_qiita
• 게시 · 편집 · 삭제 등 쓰기 계열도 사용한다면 write_qiita

발행한 토큰은 비밀번호와 같은 비밀 정보입니다. 리포지토리(Repository)에 커밋하거나 타인에게 보여주지 않도록 주의하세요. 만약 실수로 어딘가에 노출했다면, 설정 화면에서 즉시 폐기하고 새 토큰을 다시 발행하는 것이 안전합니다.

마지막으로 Claude Code에 등록합니다. 토큰은 -e KEY=value 형태로 환경 변수(Environment variable)로서 전달합니다. /path/to/...와 "당신의 토큰"은 실제 본인의 값으로 교체해 주세요.

claude mcp add qiita --transport stdio -e QIITA_ACCESS_TOKEN=당신의_토큰 -- node /path/to/unofficial-qiita-mcp/dist/index.js

등록이 완료되면 claude mcp list 또는 세션 중이라면 /mcp를 통해 상태를 확인할 수 있습니다. 이와 관련된 더 자세한 주의 사항은 GitHub의 README에 정리되어 있으므로, 잘 작동하지 않을 때는 확인해 보시기 바랍니다.

Claude Code에서 Qiita를 조작할 수 있는 MCP 서버를 소개해 드렸습니다.

검색부터 게시 · 편집 · 삭제까지 전 과정을 커버하고 있어, 터미널을 벗어나지 않고 기사를 다루고 싶은 상황에서 유용하게 활용될 것입니다.

코드는 GitHub에 공개되어 있습니다. 괜찮으시다면 사용해 보세요.

마음에 드셨다면 스타(Star)나 좋아요를, 개선할 점을 발견하셨다면 댓글을 남겨주시면 향후 개발에 큰 힘이 됩니다!

여기까지 읽어주셔서 감사합니다!