Gnostash MCP Server

AI 開発ワークフローのための知識管理システム「gnostash」を Claude Desktop や Claude Code から利用できる MCP (Model Context Protocol) サーバーです。

📋 概要

Gnostash MCP Server は、Claude Desktop や Claude Code から Gnostash のドキュメント管理機能にアクセスできるようにする Model Context Protocol (MCP) サーバーです。

🎯 このツールでできること

検索・閲覧機能

• タグ一覧の取得: 利用可能なすべてのタグとその使用回数を確認
• タグによる検索: 特定のタグ（例: claude, mcp, architecture）が付いたドキュメントを検索
• キーワード検索: タイトルや内容に特定のキーワードを含むドキュメントを全文検索
• ドメインフィルタ: 特定のドメイン（例: github.com）のドキュメントのみを抽出
• お気に入り表示: お気に入りに登録したドキュメントだけを表示
• 詳細情報の取得: 個々のドキュメントの完全な内容とメタデータを取得
• 複数取得: 複数の ID を指定して一度に複数のドキュメントを取得

作成・管理機能

• ドキュメント作成: 新しいドキュメントをタイトル、URL、内容、タグを指定して作成
• ドキュメント更新: 既存ドキュメントのタイトル、内容、タグなどを更新
• ドキュメント削除: 不要になったドキュメントを削除
• タグ管理: ドキュメントに複数のタグを付けて分類・整理

実用的な使用例

• プロジェクトの設計書（.claude/フォルダの内容など）を Gnostash に保存して後から検索
• API ドキュメントや技術メモをタグ付けして管理
• 開発中に見つけた有用な Web ページをブックマーク感覚で保存
• チームで共有したい技術資料をタグを使って整理

制限事項

• API キーによる認証が必要（Gnostash アカウントの作成が必要）
• 読み込み・書き込みの権限は API キーに紐づくユーザーのデータのみ
• API レート制限: 1 分間に 60 リクエスト、1 時間に 1000 リクエスト

🚀 事前準備

1. Gnostash アカウントの作成（必須）

このツールを使用するには、事前に Gnostash への登録が必要です。

1. Gnostash にアクセス
2. アカウントを作成（無料）
3. ログイン後、設定画面から API キーを発行
   • API キーは gsk_ で始まる文字列です
   • このキーは後で設定時に使用します

📦 インストール方法

NPM パッケージとしてインストール

# npmを使用する場合
npm install -g gnostash-mcp-server

# pnpmを使用する場合（推奨）
pnpm add -g gnostash-mcp-server

# yarnを使用する場合
yarn global add gnostash-mcp-server

⚙️ 設定方法

Claude Desktop / Claude Code での設定

1. MCP サーバーの追加（Claude Code の場合）

Claude Code で mcp add コマンドを使用する場合：

mcp add gnostash

プロンプトが表示されたら、以下を入力：

• Server name: gnostash
• Command: npx gnostash-mcp-server
• Environment variables:
  • GNOSTASH_API_KEY: 取得した API キー

2. 手動設定（.claude/claude_desktop_config.json）

Claude Desktop の設定ファイルを直接編集する場合：

macOS/Linux:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

以下の内容を追加：

{
  "mcpServers": {
    "gnostash": {
      "command": "npx",
      "args": ["gnostash-mcp-server"],
      "env": {
        "GNOSTASH_API_KEY": "gsk_your_api_key_here"
      }
    }
  }
}

3. ローカルビルド版を使用する場合

{
  "mcpServers": {
    "gnostash": {
      "command": "node",
      "args": ["/path/to/gnostash-mcp/dist/server.js"],
      "env": {
        "GNOSTASH_API_KEY": "gsk_your_api_key_here"
      }
    }
  }
}

# TypeScriptのビルド
pnpm build

# 開発モードで起動
pnpm dev

# 本番モードで起動
pnpm start

Claude Desktop 統合

設定手順

1. Claude Desktop の設定ファイルを開く

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. MCP 設定を追加

{
  "mcpServers": {
    "gnostash": {
      "command": "node",
      "args": ["/path/to/gnostash-mcp/dist/server.js"],
      "env": {
        "MCP_MODE": "stdio",
        "GNOSTASH_API_URL": "https://gnostash.tunetalk.jp/api"
      }
    }
  }
}

3. Claude Desktop を再起動

動作確認

Claude Desktop で以下のコマンドを入力して動作確認:

@gnostash list my recent stashes

🔧 トラブルシューティング

よくある問題と解決方法

1. Claude Desktop/Code でツールが表示されない

原因: 設定ファイルの記述ミスまたはパスエラー

解決方法:

• 設定ファイルの JSON 構文を確認
• API キーが正しく設定されているか確認
• Claude Desktop/Code を完全に再起動

# 設定ファイルの構文チェック
jq . ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 認証エラー（401）が発生する

原因: API キーが無効または期限切れ

解決方法:

• Gnostash のダッシュボードで新しい API キーを発行
• 設定ファイルの API キーを更新
• gsk_で始まる正しい形式のキーか確認

3. タグが登録されない

原因: タグ名に特殊文字が含まれている

解決方法:

• タグ名は英数字とハイフンのみ使用
• 日本語タグは避ける
• スペースの代わりにハイフンを使用（例: api-design）

4. "Tool not found"エラー

原因: ツール名の誤りまたは未登録

解決方法:

• 正しいツール名を使用（stash_list, stash_get 等）
• @gnostash プレフィックスを付けているか確認

デバッグモード

詳細なログを有効化:

# 環境変数でデバッグモードを有効化
{
  "mcpServers": {
    "gnostash": {
      "command": "npx",
      "args": ["gnostash-mcp-server"],
      "env": {
        "GNOSTASH_API_KEY": "gsk_your_api_key",
        "DEBUG": "true"
      }
    }
  }
}