github-kb-mcp

Personal GitHub Knowledge Base MCP server. Store, search, and manage your favorite GitHub repos with JSON files.

No SQLite. No API keys. No external services. Just pure JSON in → structured JSON out.

Install

npm install -g github-kb-mcp

Usage

Claude Desktop / Cursor / OpenCode

Add to your MCP config:

{
  "mcpServers": {
    "github-kb": {
      "command": "npx",
      "args": ["-y", "github-kb-mcp"]
    }
  }
}

Tools

add_repo — Add a GitHub Project

Add a GitHub project to your knowledge base. Automatically parses owner/name from URL.

Input:

{
  "url": "https://github.com/owner/repo",
  "description": "A test project",
  "language": "TypeScript",
  "tags": ["test", "demo"],
  "purpose": "Learning MCP",
  "install_cmd": "npm install",
  "usage_cmd": "npm run dev",
  "status": "active",
  "notes": "Great project"
}

Output:

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "owner": "owner",
  "name": "repo"
}

search_repos — Search Projects

Search the knowledge base with keyword, language, tag, and status filters.

Input:

{
  "query": "test",
  "language": "TypeScript",
  "tag": "demo",
  "status": "active",
  "limit": 20,
  "offset": 0
}

get_repo — Get Project by ID

Get full details of a single project.

Input:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

update_repo — Update Project

Update partial fields of a project. Only pass fields you want to change.

Input:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Updated description",
  "status": "archived"
}

delete_repo — Delete Project

Delete a project from the knowledge base.

Input:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

get_stats — Get Statistics

Get knowledge base statistics.

Output:

{
  "total_repos": 42,
  "by_language": { "TypeScript": 15, "Python": 10, "Rust": 8 },
  "by_status": { "active": 30, "archived": 5, "reference": 7 },
  "by_tag": { "mcp": 12, "api": 8, "test": 5 }
}

Supported Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | ✅ | GitHub project URL | | description | string | ❌ | Project description | | language | string | ❌ | Primary programming language | | tags | string[] | ❌ | Category tags | | purpose | string | ❌ | Why save this project | | install_cmd | string | ❌ | Install command | | usage_cmd | string | ❌ | Usage command | | status | enum | ❌ | active, archived, reference, wip | | notes | string | ❌ | Free-form notes |

Data Storage

All data is stored in data/github-kb.json — a simple JSON file that you can:

• Edit with any text editor
• Commit to Git for version control
• Backup by copying the file
• Share with others

Design

| Feature | Why | |---------|-----| | Zero DB | No SQLite, no setup, instant startup | | Zero API keys | No GitHub API needed, you manage the data | | JSON file storage | Human-readable, Git-friendly, easy to backup | | Single file | Easy to maintain, easy to audit | | UUID-based IDs | No auto-increment conflicts |

License

MIT