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

Related MCP server: obsidian-kb

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).

2. 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

3. 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

• Built on @modelcontextprotocol/sdk

• Inspired by the MCP community

• Special thanks to Anthropic for Claude Code