Business Card MCP

AI-native, self-hostable private business card library. Users upload business cards in ChatGPT, where the existing multimodal model recognizes and confirms them; the Remote MCP handles verification, private storage, search, modification, archiving, and export, without making additional model API calls.

Features

• ChatGPT Remote MCP: create, search, read, update, archive, and export business cards

• Private admin website: self-set password login, card wall / list view, protected thumbnails

• D1 FTS5: search by name, company, title, phone, email, address, tags, occasion, and notes

• R2: private Markdown and 480px WebP thumbnails

• KV: per-user bc_ Connector Key

• Returns a clickable business card confirmation page after writes

• Thumbnail is a required field when creating a business card, avoiding records without images

Currently it is keyword full-text search, not embedding/vector semantic search.

Related MCP server: DuckPond MCP Server

Architecture

ChatGPT / Claude
       │ Remote MCP
       ▼
Cloudflare Worker ── WEB_PASSWORD 或可選 Cloudflare Access JWT 驗證
       ├── D1：聯絡人與 FTS5
       ├── R2：Markdown、WebP 縮圖
       ├── KV：MCP Key
       └── Static Assets：私人管理網站

Original business card images are not saved by default. The GitHub repo contains only code, migrations, and synthetic test data, and no user contacts.

MCP Tools

Deployment Requirements

• Node.js 20+

• Cloudflare account

• Wrangler CLI logged into the correct Cloudflare account

Deployment

1. Install and Set Up Local Configuration

npm install
cp public/config.example.js public/config.js

wrangler.jsonc ships with the repo as a zero-value placeholder (the SmallGreen standard requires statically determinable resource declarations); fill in the real IDs in the next step. After filling them in, it is recommended to run git update-index --skip-worktree wrangler.jsonc to avoid committing the real IDs. public/config.js is already ignored by Git; web authentication requires no frontend configuration.

2. Create Cloudflare Resources

npx wrangler d1 create business-card-mcp
npx wrangler r2 bucket create business-card-mcp-assets
npx wrangler kv namespace create CARD_KEYS

Fill the account, D1, and KV IDs returned by Cloudflare into wrangler.jsonc, and set:

• PUBLIC_BASE_URL

• R2 bucket name

Then set the self-set password for web login; the password only goes through Wrangler secrets and is not written into wrangler.jsonc:

npx wrangler secret put WEB_PASSWORD

CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD can be left empty by default; leaving them empty means the web page uses password login with zero card binding.

3. Optional Upgrade: Cloudflare Access Email OTP

Set this up only if you want Cloudflare to do an email One-Time PIN at the edge first. Zero Trust onboarding may require binding a credit card; the free plan itself is $0.

1. In Cloudflare Zero Trust, create a self-hosted Access application protecting this Worker's domain.

2. Enable One-Time PIN as the login method, and restrict who can log in with an email or email domain policy.

3. Confirm that the browser UI and /api/* are both within the Access protection scope.

4. Exempt the /mcp path from the Access login requirement, for example with a path-based Bypass policy or by splitting it into a route rule that does not apply Access. /mcp is still authenticated by the bc_ MCP key; ChatGPT/Claude will not carry a Cloudflare Access cookie.

5. Fill the Access application's Audience tag into CF_ACCESS_AUD and the Zero Trust team domain into CF_ACCESS_TEAM_DOMAIN, then redeploy. Once filled, web requests that pass Access are automatically allowed without asking for the self-set password.

4. Migration, Testing, and Deployment

npx wrangler types
npm run typecheck
npm test
npx wrangler d1 migrations apply business-card-mcp --remote
npx wrangler deploy

5. Connect to ChatGPT

1. Open the deployed website and enter the self-set password configured in WEB_PASSWORD; if Cloudflare Access has been enabled, verification is done via email One-Time PIN.

2. Generate a business card MCP Key.

3. Copy the full Connector URL; the URL contains the Key, so treat it like a password.

4. Add a Remote MCP in ChatGPT developer mode.

5. After scanning the tools, test with "use the business card MCP to search for someone".

Local Development

npm run migrate:local
npm run dev

Health check: GET /healthz

Remote MCP: POST /mcp

Security and Privacy

• All business card queries are restricted to the password-logged-in owner, the Cloudflare Access sub, or the MCP Key owner.

• The R2 bucket stays private; thumbnails are served by a login-protected API.

• MCP accepts both Bearer tokens and Connector URL query tokens.

• The full Key is shown only at creation time and supports individual revocation.

• Do not commit .env, .dev.vars, wrangler.jsonc, or public/config.js.

Please report security issues privately per SECURITY.md; do not open a public Issue.

Verification

npm test
npm run typecheck
npm audit --omit=dev

The project currently has unit, MCP protocol, Web API, permission, storage, and UI contract tests; the coverage threshold is 80% for lines/functions/statements and 75% for branches.

Known Limitations

• Vector semantic search is not yet available.

• There is no interface yet to add images to existing business cards without images; new records already enforce a required thumbnail.

• Permanent deletion is not enabled by default; use archiving to avoid accidental deletion.

License

Apache-2.0. See LICENSE for details.