mcp-github-db-server
Provides structured tools for interacting with GitHub repositories, including listing repositories, reading files, listing directory contents, searching code, listing issues, creating issues, and listing pull requests.
Provides tools for interacting with a local SQLite database, including listing tables, describing table schemas, running read-only queries, executing write statements or DDL, and upserting project records.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-github-db-server list open issues on my repo and save a summary to the database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-github-db-server
An MCP (Model Context Protocol) server that gives AI agents — Claude Code, Claude Desktop, or any other MCP client — structured, tool-based access to GitHub repositories and a local SQLite database, plus a set of custom Claude Code skills built on top of it.
Instead of an agent shelling out to git/curl or hallucinating repo
structure, it gets a small, well-typed toolset: browse a repo's file tree,
read files, search code, list/create issues and PRs, and query or update a
local database — all with Zod-validated inputs and JSON-safe outputs.
Why this exists
Agents are most useful when they have narrow, auditable tools instead of raw shell access. This project is a small, readable reference for that pattern:
One MCP server, two backends. GitHub (via Octokit) and SQLite (via
better-sqlite3) are exposed through the same tool-calling interface, so an agent can cross-reference "what's in this repo" with "what have I already recorded about it" in one conversation.Claude Code skills on top. Three skills (
github-explorer,db-assistant,repo-health-check) show how to turn a raw toolset into guided workflows — when to call which tool, how to summarize results, and where to stop and ask before taking a write action.
Related MCP server: GitHub Dev Copilot
Architecture
┌─────────────────────────┐
Claude Code / │ MCP Client (stdio) │
Claude Desktop ├─────────────────────────┤
│ Claude Code Skills │
│ • github-explorer │
│ • db-assistant │
│ • repo-health-check │
└───────────┬─────────────┘
│ MCP (tools/list, tools/call)
┌───────────▼─────────────┐
│ mcp-github-db-server │
│ ┌─────────┐ ┌─────────┐ │
│ │ github │ │database │ │
│ │ tools │ │ tools │ │
│ └────┬────┘ └────┬────┘ │
└───────┼───────────┼──────┘
│ │
┌──────▼───┐ ┌────▼──────┐
│ GitHub │ │ SQLite │
│ REST API │ │ (local) │
└──────────┘ └───────────┘Tools
GitHub (src/tools/github.ts)
Tool | Description |
| List repos visible to the authenticated token |
| Read a file's contents at a given ref |
| List entries at a path (directory listing) |
| Search code via GitHub's code search |
| List issues, filtered by state |
| Create a new issue |
| List pull requests, filtered by state |
Database (src/tools/database.ts)
Tool | Description |
| List tables in the local SQLite database |
| Show a table's columns/types |
| Run a read-only |
| Run a write statement ( |
| Idempotent insert/update into the |
db_query and db_execute are intentionally split so a client can offer
"read-only mode" by only ever calling the former.
Claude Code skills (.claude/skills/)
github-explorer— browsing, searching, and summarizing a GitHub repo.db-assistant— querying and safely writing to the local database.repo-health-check— a composite workflow that pulls live GitHub signal (open issues/PRs, missing hygiene files) and snapshots it into the database so repeat checks can show a trend over time.
Each SKILL.md documents when to use which tool, not just what the tool
does — e.g. preferring github_search_code over guessing file paths, or
narrating a DELETE before running it.
Setup
git clone https://github.com/<your-username>/mcp-github-db-server.git
cd mcp-github-db-server
npm install
cp .env.example .env # then fill in GITHUB_TOKEN
npm run buildGITHUB_TOKEN needs repo scope (classic PAT) or equivalent fine-grained
read/write access to whichever repositories you want the agent to touch.
GITHUB_DEFAULT_OWNER / GITHUB_DEFAULT_REPO are optional — set them to
avoid passing owner/repo on every call.
Running standalone
npm startThe server speaks MCP over stdio and logs a one-line startup message to stderr (stdout is reserved for the protocol).
Connecting to Claude Code / Claude Desktop
Copy .mcp.json.example to .mcp.json (project-scoped) or merge it into your
global Claude Desktop config, filling in your token:
{
"mcpServers": {
"github-db": {
"command": "node",
"args": ["./dist/index.js"],
"env": {
"GITHUB_TOKEN": "ghp_...",
"DATABASE_PATH": "./data/app.sqlite"
}
}
}
}The .claude/skills/ directory in this repo is picked up automatically by
Claude Code when you open this folder as a project, so the three skills above
become available alongside the MCP tools.
Seeding the database
npm run db:seedCreates data/app.sqlite (if it doesn't exist) and inserts a starter row into
the projects table.
Development
npm run dev # run the server directly with tsx (no build step)
npm run typecheck # tsc --noEmitSecurity notes
db_queryrejects anything that isn'tSELECT/WITH/EXPLAIN; writes must go throughdb_execute.All table/column identifiers used in dynamic SQL are validated against
^[A-Za-z_][A-Za-z0-9_]*$before being interpolated — user-supplied values always go through parameterized placeholders instead.GITHUB_TOKENis read from the environment only; it's never logged or echoed back through a tool response..envand the SQLite data directory are git-ignored by default.
License
MIT — see LICENSE.
Available Tools
12 toolsdb_describe_tableB
Show column names, types, and constraints for a table.
Inputs: table (required).
db_executeB
Run a write statement (INSERT/UPDATE/DELETE/CREATE TABLE) against the local database. Returns affected row count.
Inputs: sql (required), params.
db_list_tablesB
List all tables in the local SQLite database.
Inputs: no named parameters.
db_queryA
Run a read-only SQL query (SELECT/WITH/EXPLAIN only) against the local database and return the rows.
Inputs: sql (required), limit (required), params.
db_upsert_projectB
Convenience helper: insert or update a row in the projects table by unique project name.
Inputs: name (required), notes, repoFullName.
github_create_issueC
Create a new issue in a GitHub repository.
Inputs: title (required), body, repo, owner, +1 more.
github_get_fileB
Read a file's contents from a GitHub repository at a given ref.
Inputs: path (required), ref, repo, owner.
github_list_directoryC
List files and subdirectories at a given path in a GitHub repository.
Inputs: path (required), ref, repo, owner.
github_list_issuesC
List issues for a repository, optionally filtered by state.
Inputs: state (required), perPage (required), repo, owner.
github_list_pull_requestsC
List pull requests for a repository, optionally filtered by state.
Inputs: state (required), perPage (required), repo, owner.
github_list_reposA
List repositories visible to the authenticated GitHub token (own repos, plus any orgs the token can see).
Inputs: type (required), perPage (required).
github_search_codeB
Search code across GitHub (or scoped to one repo) using GitHub's code search syntax.
Inputs: query (required), perPage (required), repo, owner.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have clearly distinct resource-and-action purposes: GitHub reads, issue creation, PR listing, and DB read/write/table inspection are separable. The main overlap is db_upsert_project versus db_execute, since upsert_project is a specialized write helper that could also be done via generic execution.
The set follows a predictable domain-prefixed verb_noun pattern: github_list_repos, github_get_file, db_list_tables, db_describe_table, db_upsert_project. Minor deviations are db_query and db_execute, which omit a noun object but remain clear and consistent with the db_ prefix.
Twelve tools is well within a reasonable range for a server combining GitHub reads/issue creation with local SQLite access. Each tool covers a distinct operation, and the surface does not feel bloated or thin.
The database side is fairly complete with table listing, schema description, read queries, writes, and an upsert helper. The GitHub side is notably incomplete: it can list issues and create issues, but has no update/close/get issue, no PR creation or merge, and no PR detail or comment operations.
Maintenance
Related MCP Connectors
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted MCP server for live public-data APIs and Skills for AI agents.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server that exposes GitHub operations as tools for AI agents, enabling code search, issue management, and PR review.1236 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with GitHub via MCP, managing repositories, issues, PRs, and analyzing repository health through tools like list_repositories, read_issues, create_issue, comment_on_pr, and analyze_repo_health.-
- FlicenseNot gradedqualityCmaintenanceEnables AI clients such as Cursor to interact with GitHub repositories and perform issue listing, triage, health checks, prioritization, commenting, weekly digests, and release-note generation through purpose-built MCP tools.-
- FlicenseAqualityCmaintenanceExposes GitHub, SQLite database, and calendar tools, resources, and prompts over MCP so any MCP client can query data, manage issues, and schedule events.12-