claude-mcp-kb

grandinh/claude-mcp-kb

3.2

If you are the rightful owner of claude-mcp-kb and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Claude MCP Knowledge Base is a server designed to streamline Model Context Protocol (MCP) development by providing a persistent knowledge base with GitHub integration and a removal blocklist.

Tools
6
Resources
0
Prompts
0

Claude MCP Knowledge Base

Eliminate repeated MCP research - A persistent knowledge base server for Model Context Protocol (MCP) development with GitHub integration and removal blocklist.

Features

  • Zero-Research MCP Creation: Built-in knowledge of MCP specifications, best practices, and patterns
  • Always Up-to-Date: Automatically syncs from official MCP repositories and community examples
  • GitHub Integration: Indexes your .claude/ directories across all repositories
  • Removal Blocklist: Track deleted MCPs and exclude file patterns permanently
  • Periodic Sync: Auto-updates knowledge base every 30 minutes (configurable)
  • Fast Search: Keyword-based search across all indexed documentation

Quick Start

Prerequisites

  • Node.js ≥18
  • GitHub Personal Access Token (for indexing repos)

Installation

npm install -g @grandinharrison/claude-mcp-kb

Or use with npx:

npx @grandinharrison/claude-mcp-kb

Setup

  1. Set GitHub Token:
export GITHUB_TOKEN="your_github_pat_here"

Or authenticate with Claude Code (token will be auto-detected from ~/.claude/.credentials.json).

  1. Add to Claude Code:

Add to your .claude/settings.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "npx",
      "args": ["-y", "@grandinharrison/claude-mcp-kb"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Or use the CLI:

claude mcp add --transport stdio knowledge-base -- npx @grandinharrison/claude-mcp-kb
  1. First Run:

The server will automatically:

  • Create ~/.claude-kb/ directory
  • Index official MCP repositories
  • Discover your repos with .claude/ directories
  • Start periodic sync (every 30 minutes)

Usage

Available Tools

search_knowledge_base

Search MCP documentation, examples, and best practices.

{
  "query": "how to implement MCP tool with error handling",
  "maxResults": 10
}

Returns: Ranked search results with snippets and source files.

get_mcp_specification

Get current MCP protocol spec, best practices, and common patterns.

{}

Returns: Complete MCP specification with lifecycle, transports, capabilities.

list_repositories

List all indexed repositories with file counts.

{}

Returns: Repository list with counts.

add_blocklist_entry

Add MCP server or file pattern to blocklist.

{
  "type": "file_pattern",
  "pattern": "**/*.secret.md",
  "reason": "Contains sensitive information"
}

Or block a server:

{
  "type": "server",
  "serverName": "@example/bad-mcp-server",
  "reason": "Security vulnerability"
}
check_blocklist

Check if something is blocked.

{
  "serverName": "@example/my-server"
}
update_knowledge_base

Manually trigger sync (normally automatic).

{
  "force": true
}

Configuration

Edit ~/.claude-kb/config.json:

{
  "version": "1.0.0",
  "repositories": [
    {
      "owner": "your-org",
      "repo": "your-repo",
      "branch": "main",
      "includePatterns": [".claude/**/*.md"],
      "excludePatterns": ["**/node_modules/**"],
      "indexingEnabled": true,
      "type": "user"
    }
  ],
  "sync": {
    "enabled": true,
    "intervalMinutes": 30,
    "autoDiscoverUserRepos": true,
    "includeOfficialMCPRepos": true,
    "includeCommunityRepos": true
  },
  "storage": {
    "cacheDir": "~/.claude-kb",
    "maxIndexSizeMB": 1000
  },
  "blocklist": {
    "enabled": true,
    "strict": true
  }
}

Configuration Options

  • repositories: Explicitly configured repos to index
  • sync.intervalMinutes: How often to sync (5-1440 minutes)
  • sync.autoDiscoverUserRepos: Auto-find your repos with .claude/ dirs
  • sync.includeOfficialMCPRepos: Index modelcontextprotocol/* repos
  • sync.includeCommunityRepos: Index awesome-mcp-servers lists
  • blocklist.strict: Block without prompting user

Blocklist

The blocklist is stored in ~/.claude-kb/data/blocklist.json as an append-only log.

Block a File Pattern

{
  "type": "file_pattern",
  "pattern": "**/private/**",
  "reason": "Exclude private directories"
}

Block an MCP Server

{
  "type": "server",
  "serverName": "@malicious/mcp-server",
  "version": "1.0.0",
  "reason": "Security vulnerability CVE-2025-12345"
}

Removal is Permanent

Once blocked, entries remain in the log forever (unless manually edited). To override:

  1. Edit ~/.claude-kb/data/blocklist.json
  2. Set allowOverride: true on the entry
  3. Restart server

Storage Structure

~/.claude-kb/
├── config.json              # Configuration
├── data/
│   ├── specification.json   # MCP spec cache
│   └── blocklist.json       # Blocklist log
├── repos/                   # Cached repository content
│   ├── modelcontextprotocol/
│   │   └── servers/
│   └── your-username/
│       └── your-repo/
└── templates/               # MCP templates (future)

Development

Build from Source

git clone https://github.com/grandinharrison/claude-mcp-kb.git
cd claude-mcp-kb
npm install
npm run build

Run in Dev Mode

npm run dev

Run Tests

npm test

Roadmap

Current (v0.1.0)

  • ✅ Basic keyword search
  • ✅ GitHub integration
  • ✅ Periodic sync
  • ✅ Blocklist (servers + file patterns)
  • ✅ Official MCP repos indexing
  • ✅ Auto-discover user repos

Planned (v0.2.0)

  • Vector search (txtai/FAISS integration)
  • Semantic similarity scoring
  • MCP server templates generation
  • Real-time webhook sync
  • Web UI for blocklist management

Future

  • Multi-cloud support (GitLab, Bitbucket)
  • Team collaboration features
  • Usage analytics
  • Knowledge graph relationships

Troubleshooting

"GitHub token not found"

Set GITHUB_TOKEN environment variable or authenticate with Claude Code.

"Error fetching repo"

Check:

  1. Token has repo scope
  2. Repository exists and you have access
  3. Network connectivity

Knowledge base not updating

  1. Check ~/.claude-kb/config.json - ensure sync.enabled: true
  2. Manually trigger: update_knowledge_base tool
  3. Check logs in stderr output

Slow searches

Current MVP uses keyword search. Upgrade to vector search in v0.2.0 for faster semantic search.

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

License

MIT License - see LICENSE file

Author

Harrison Grandin

Acknowledgments