MCP Server

Bayt al-Hiqma

Connect ChatGPT to your GitHub-backed Obsidian vault.

Bayt al-Hiqma is an MCP bridge between ChatGPT and a private Obsidian vault stored in GitHub. Your vault stays in GitHub. ChatGPT gets structured, permissioned context.

Architecture

How ChatGPT connects to your Obsidian notes through Bayt al-Hiqma.

ChatGPT
AI Assistant
Bayt al-Hiqma
MCP Server
GitHub API
REST
vault repo
Private
Markdown
Obsidian Notes

ChatGPT authenticates to Bayt al-Hiqma using MCP_BEARER_TOKEN.

Bayt al-Hiqma authenticates to GitHub using GITHUB_TOKEN.

ChatGPT never receives the GitHub token.

Obsidian

Human writing interface

GitHub

Durable source of truth

Bayt al-Hiqma

Secure bridge

Setup Checklist

Follow these steps to connect your vault to ChatGPT.

Create or choose your private vault repo

Create a private GitHub repository to store your Obsidian vault.

Recommended repo name: vault

Example: your-username/vault

Add your Obsidian Markdown files to this repository.

Create a fine-grained GitHub token

Generate a personal access token with minimal required permissions.

Restrict access to only the vault repository.

Grant Contents read/write permission.

Grant Metadata read permission.

Do not use a broad account token.

Deploy Bayt al-Hiqma

Deploy the MCP server to Vercel and configure environment variables.

Deploy bayt-al-hiqma/mcp to Vercel.

Add all required environment variables in Vercel project settings.

Confirm /api/health returns healthy.

Connect ChatGPT

Add the MCP server as a custom connector in ChatGPT.

Use the deployed /mcp URL.

Add it as a custom MCP app/connector in ChatGPT.

Use your MCP_BEARER_TOKEN for authorization.

Test the tools

Try these example prompts in ChatGPT.

"Search my vault for notes about Staff promotion."
"Resolve the note called Staff Promotion."
"Read my daily note from today."
"Create a note called test/chatgpt-connection.md."
"Find backlinks for Staff Promotion."
"Show me the local graph around Comp Alignment."
"Append a distilled note from this conversation to today's daily note."

Environment Variables

Generate a .env.local block for your Vercel deployment.

GITHUB_TOKEN=github_pat_xxx
GITHUB_OWNER=your-username
GITHUB_REPO=vault
GITHUB_BRANCH=main
MCP_BEARER_TOKEN=replace-with-long-random-secret
VAULT_ROOT=
DAILY_NOTES_DIR=daily
DEFAULT_AUTHOR_NAME=Bayt al-Hiqma
DEFAULT_AUTHOR_EMAIL=bayt@bayt-al-hiqma.local
MAX_SEARCH_RESULTS=20
MAX_GRAPH_NODES=50
MAX_FILE_SIZE_KB=512

Configure these variables in your Vercel project settings. Never store real tokens in this form.

Security

Best practices for keeping your vault secure.

  • Keep your vault repository private.
  • Use a fine-grained GitHub PAT restricted to only the vault repo.
  • GITHUB_TOKEN is never exposed to the client or ChatGPT.
  • Start with read/append/create operations before destructive edits.
  • Git commits serve as audit history for all changes.
  • No delete, rename, or bulk refactor tools in v1.
  • Use git history to rollback mistakes.

MCP Tools

Tools exposed by the MCP server for ChatGPT to use.

resolve_note

Resolve note identity by title, alias, path, or wikilink.

resolve_note({ nameOrPath: "[[Staff Promotion]]" })

search_notes

Search vault with Obsidian-aware ranking across title, aliases, tags, content.

search_notes({ query: "career", tag: "promotion" })

read_note

Read note with full context: backlinks, mentions, related notes.

read_note({ path: "work/staff-promotion.md" })

recent_notes

List recently changed notes.

recent_notes({ days: 7, limit: 10 })

append_daily_note

Append distilled content to daily note.

append_daily_note({ content: "...", tags: ["reflection"] })

create_note

Create new note with frontmatter and links.

create_note({ path: "work/new-idea.md", content: "..." })

propose_note_update

Suggest improvements without committing changes.

propose_note_update({ path: "...", instructions: "add links" })

update_note

Update existing note (requires explicit call).

update_note({ path: "...", content: "...", expectedSha: "..." })

find_backlinks

Find linked and unlinked mentions of a note.

find_backlinks({ note: "Staff Promotion" })

get_note_graph

Build local graph around a note.

get_note_graph({ noteOrQuery: "Staff Promotion", depth: 1 })

extract_tasks

Extract Markdown tasks from vault.

extract_tasks({ includeCompleted: false })