notes-mcp

A remote MCP server that captures notes into a Git-backed Markdown vault (Obsidian-friendly). Deploy your own instance to Cloudflare Workers in one click.

What & why

notes-mcp lets any MCP client — Claude, Claude Desktop, Cursor, and others — append and create Markdown notes directly in a GitHub repository. It's designed for an Obsidian vault synced via git (obsidian-git): capture a thought from a chat with Claude, and it shows up in your vault the next time Obsidian pulls.

Each deployment is single-tenant — you run your own instance, pointed at your own notes repo, protected by your own auth token. Nothing is hardcoded; everything is configuration.

Features

• Five focused tools: append to a note, create/overwrite a note, append to today's daily note, read a note, list a directory.

• Single-file edge deploy — one Cloudflare Worker, no servers to manage.

• Runs on Cloudflare's free tier.

• Works with any Git-backed Markdown vault, not just Obsidian.

• Token-guarded — every request to /mcp requires a bearer token you control.

How it works

MCP client  →  Worker (/mcp)  →  GitHub Contents API  →  your notes repo  →  Obsidian Git pulls it

Your MCP client calls a tool (e.g. append_note). The Worker authenticates the request, then reads/writes the target file through the GitHub Contents API, which creates a commit. The note appears on your other devices the next time Obsidian Git pulls — tune its auto-pull / pull-on-startup settings for how fresh you want that to be.

Prerequisites

• A Cloudflare account (free tier is enough).

• A GitHub repository to hold your notes (can be the same repo as your Obsidian vault).

• A fine-grained GitHub Personal Access Token scoped to that repo.

Create the PAT

1. Go to github.com/settings/personal-access-tokens.

2. Click Fine-grained tokens → Generate new token.

3. Set Resource owner to yourself (or the org that owns your notes repo).

4. Under Repository access, choose Only select repositories and pick your notes repo.

5. Under Repository permissions, set Contents to Read and write. Leave everything else as No access.

6. Generate the token and copy it — you'll only see it once.

Deploy

A. One-click deploy

1. Click the Deploy to Cloudflare button above.

2. Cloudflare will fork/clone this repo and prompt you for the two secrets below (GITHUB_PAT, MCP_AUTH_TOKEN) during setup.

3. After deploying, open your Worker in the Cloudflare dashboard and set the vars (GITHUB_OWNER, GITHUB_REPO, etc.) under Settings → Variables.

B. CLI

git clone https://github.com/Vontk/notes-mcp.git
cd notes-mcp
npm install

# Edit the "vars" block in wrangler.jsonc for your repo/timezone/etc.

npx wrangler secret put GITHUB_PAT
npx wrangler secret put MCP_AUTH_TOKEN   # e.g. generate with: openssl rand -hex 32

npm run deploy

Configuration

Connect to Claude

Claude.ai (custom connector):

1. Go to claude.ai/customize/connectors.

2. Click + Add custom connector.

3. URL: https://<your-worker>.<your-subdomain>.workers.dev/mcp

4. Pass your token either as an Authorization: Bearer <MCP_AUTH_TOKEN> header, or by appending ?token=<MCP_AUTH_TOKEN> to the URL.

Claude Desktop / other clients (via mcp-remote):

{
  "mcpServers": {
    "notes-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-worker>.<your-subdomain>.workers.dev/mcp?token=<MCP_AUTH_TOKEN>"
      ]
    }
  }
}

Tools

Security

• Each deployment is single-tenant: one Worker, one notes repo, one token.

• Keep MCP_AUTH_TOKEN secret — anyone with it can read and write to your notes repo through this Worker.

• Scope GITHUB_PAT to exactly one repository with Contents: Read and write only.

• Never commit secrets. .dev.vars and .wrangler are gitignored; use .dev.vars.example as a template.

• To rotate a credential, generate a new value and run wrangler secret put <NAME> again — it overwrites the existing secret immediately.

Local dev

npm start

Test it with the MCP Inspector:

npx @modelcontextprotocol/inspector

Point it at http://localhost:8787/mcp with your MCP_AUTH_TOKEN from .dev.vars.

Testing / CI

npm run typecheck
npm run lint
npm test

ci.yml runs all three on every pull request and push. deploy.yml deploys to Cloudflare on every push to main, once those checks pass — it needs two repo secrets under Settings → Secrets and variables → Actions:

• CLOUDFLARE_API_TOKEN

• CLOUDFLARE_ACCOUNT_ID

Contributing

Issues and pull requests are welcome. Please run npm run lint, npm run typecheck, and npm test before submitting.

License

MIT