PKB MCP Server

A Python MCP (Model Context Protocol) server that provides a Personal Knowledge Base backed by a GitHub repository. TIL entries, prompts, and patterns are stored as Markdown files and managed through a set of tools exposed via the MCP protocol.

Tools

The server exposes 5 tools:

Tool	Description
add_til	Create a "Today I Learned" entry with a title, content, and tags.
add_prompt	Save a reusable prompt in a category (coding, infrastructure, documentation, general).
add_pattern	Document a reusable pattern in a category (agent, cloud, devops).
search_pkb	Search the entire knowledge base by keyword.
list_entries	Browse entries in a section (til, prompts, patterns, or all).

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Yes	A GitHub personal access token with Contents: Read and write permissions on the target repository.
GITHUB_REPO	No	The GitHub repository in owner/repo format. Defaults to pdawson1983/dawson-pkb.

GitHub Token Setup

1. Go to GitHub Settings > Developer settings > Fine-grained tokens.
2. Click Generate new token.
3. Give the token a descriptive name (e.g. pkb-mcp-server).
4. Under Repository access, select the repository you want to use as your knowledge base.
5. Under Permissions > Repository permissions, set Contents to Read and write.
6. Click Generate token and copy the value.

Docker

Build

docker build -t pkb-mcp-server .

Run

docker run -i --rm \
  -e GITHUB_TOKEN="your-github-token-here" \
  -e GITHUB_REPO="owner/repo" \
  pkb-mcp-server

Claude Desktop Integration

Add the following to your claude_desktop_config.json to use this server with Claude Desktop:

{
  "mcpServers": {
    "pkb": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "pkb-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"
      }
    }
  }
}

The GITHUB_REPO environment variable should be set inside the container (e.g. baked into the image or added to the args with an additional -e GITHUB_REPO=owner/repo flag).