drizzle-docs-mcp

An MCP server that gives your AI assistant the whole Drizzle ORM documentation:
446 pages across 6 SQL dialects, with typo-tolerant search and full-text
search, served as clean Markdown.

• Built on tmcp — no framework baggage, just tools.
• Two ways to run it: npm (npx drizzle-docs-mcp, stdio) and https
  (Streamable HTTP, host it yourself with Docker or plain Node/Bun).
• Reads orm.drizzle.team/llms.txt for the catalogue and llms-full.txt for
  content search, so it follows the real docs structure instead of scraping a
  sidebar and guessing.

Connect

1. npm (stdio) — nothing to install

npx -y drizzle-docs-mcp        # Node
bunx drizzle-docs-mcp          # Bun

Or add it to your editor's MCP config:

{
  "mcpServers": {
    "drizzle-docs": {
      "command": "npx",
      "args": ["-y", "drizzle-docs-mcp"]
    }
  }
}

Cursor — Settings → MCP → Add new MCP server:

{
  "drizzle-docs": {
    "command": "npx",
    "args": ["-y", "drizzle-docs-mcp"]
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "drizzle-docs": { "command": "npx", "args": ["-y", "drizzle-docs-mcp"] }
  }
}

VS Code (Copilot) — .vscode/mcp.json or the MCP: Add Server command:

{
  "servers": {
    "drizzle-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "drizzle-docs-mcp"]
    }
  }
}

Claude Code

claude mcp add drizzle-docs -- npx -y drizzle-docs-mcp

Zed — ~/.config/zed/settings.json:

{
  "context_servers": {
    "drizzle-docs": {
      "command": { "path": "npx", "args": ["-y", "drizzle-docs-mcp"] }
    }
  }
}

2. https (Streamable HTTP) — host it yourself

The same server can listen on a port. Set MCP_TRANSPORT=http (or pass
--http) and the MCP endpoint is served at /mcp:

docker build -t drizzle-docs-mcp .
docker run --rm -p 3000:3000 drizzle-docs-mcp
curl http://localhost:3000/        # {"name":"drizzle-docs-mcp","version":"3.0.0",…}

Without Docker:

bun install && bun run build
node dist/index.js --http          # PORT, HOST, MCP_PATH come from the env

Then point a client at it:

{
  "mcpServers": {
    "drizzle-docs": { "type": "http", "url": "https://<your-host>/mcp" }
  }
}

Runs on Node 22+ or Bun, so any container platform, VM or PaaS works —
tmcp speaks plain Web Request/Response, which is why the same code serves
stdio locally and HTTP remotely.

[!NOTE]
v2 ran on Mastra Cloud (drizzle.mastra.cloud). That endpoint is retired —
use npx for local use, or self-host for a shared URL. See
CHANGELOG.md.

Tools

• depth: "index" (default) fuzzy-searches titles, slugs and sections
  straight from llms.txt — instant, and it tolerates typos (migraton
  finds Migrations).
• depth: "full" downloads llms-full.txt once (a few MB) and searches
  the actual page text, returning a snippet around each match. Use it when
  you need the answer, not a link.
• Slugs look like docs/pg/select. Some catalogue links point at pages the
  site serves without the dialect segment (/docs/pg/overview →
  /docs/overview) — fetch_page retries the unprefixed URL and repairs the
  catalogue, so you never have to care.

Ask your assistant things like:

• "How do I set up a Postgres schema in Drizzle?"
• "Which migration pages exist for SQLite?"
• "Show me the batch API examples" → search_docs { query: "batch api", depth: "full" }

Skills

The repo ships an agent skill that teaches your assistant how to use these
tools (when to use which one, and the gotchas above). Install it:

# From the skills registry (same pattern as DocShark)
npx skills add Michael-Obele/drizzle-docs --skill drizzle-docs

Or by hand into the standard skill folder:

mkdir -p ~/.agents/skills/drizzle-docs
curl -fsSL https://raw.githubusercontent.com/Michael-Obele/drizzle-docs/master/skills/drizzle-docs/SKILL.md \
  -o ~/.agents/skills/drizzle-docs/SKILL.md

• GitHub Copilot and OpenCode read ~/.agents/skills/ automatically.
• Claude Code: ln -s ../../.agents/skills/drizzle-docs ~/.claude/skills/drizzle-docs
• In this repo the skill lives in skills/drizzle-docs/ and is symlinked into
  .agents/, .agent/ and .windsurf/, so every supported editor picks it up
  from a clone.

Also: DocShark

This server answers one site — Drizzle's. If you work across many
documentation sites, use DocShark
(our own docs MCP, also built on tmcp): it crawls any docs site, stores it in
SQLite with FTS5/BM25 search, and lets your assistant query the latest pages.

bun add -g docshark

docshark add https://orm.drizzle.team/ --depth 2   # index a site
docshark search "relational queries"               # CLI search
docshark list                                      # what is indexed
docshark stale                                     # refresh anything >14 days old

Add it to your MCP config:

{
  "mcpServers": {
    "docshark": {
      "command": "bunx",
      "args": ["-y", "docshark", "start", "--stdio"]
    }
  }
}

Its agent skills are one command away too:

npx skills add Michael-Obele/docshark --skill docshark
npx skills add Michael-Obele/docshark --skill using-docshark

Use them together: drizzle-docs-mcp for instant, always-fresh Drizzle
answers, DocShark for everything else you index. See
DocShark on GitHub →.

Configuration

All optional — defaults work out of the box.

Local development

bun install          # dependencies
bun run dev          # stdio, watch mode
bun run dev:http     # HTTP on :3000/mcp
bun run check        # tsc --noEmit
bun test             # parser + search tests (offline fixtures)
bun run build        # emit dist/ (this is what npm ships)

Publishing a release

One push of a version tag runs .github/workflows/release.yml, which
typechecks, tests, builds, then publishes to npm and cuts a GitHub release:

# 1. bump "version" in package.json
bun run build        # sanity check locally
git commit -am "chore: release vX.Y.Z"
git tag vX.Y.Z && git push origin vX.Y.Z

The workflow refuses to publish if the tag does not match package.json, and
prepublishOnly re-runs check + test + build before npm publish
(provenance enabled). Requires one secret: NPM_TOKEN.

Architecture

• MCP_ARCHITECTURE.md — how the server, the data layer
  and the transports fit together.
• src/lib/docs.ts — catalogue (llms.txt), page fetching + Markdown
  conversion, full corpus (llms-full.txt), caching.
• src/lib/search.ts — Fuse.js indexes for the fast and the deep search.
• src/tools/ — the three tools.
• src/server.ts + src/index.ts — server assembly and transport selection.

Contributing

Read the Contributing Guidelines and
Code of Conduct first. Issues and security reports go to
Security.

License

MIT

Contact

• Issues & Support: [email protected]
• Contributions: [email protected]
• Maintainer: Michael Amachree ([email protected])