Craft MCP Server

A remote Model Context Protocol (MCP) server for Craft document management, deployed on Cloudflare Workers. This server enables AI assistants like Claude to read, write, search, and manage Craft documents and collections.

Features

• Document Management: Read, write, search, and delete content in Craft documents

• Collection Support: Work with Craft collections (similar to Notion databases)

• Multi-Document: Support for multiple Craft documents via configuration

• GitHub OAuth Authentication: Secure access control using GitHub accounts

• Serverless: Deployed on Cloudflare Workers with Durable Objects

Setup

1. Clone and Install

git clone <your-repo-url>
cd craft-mcp
npm install

2. Create GitHub OAuth App

1. Go to GitHub Settings → Developer settings → OAuth Apps

2. Click New OAuth App

3. Fill in:

   • Application name: Craft MCP Server

   • Homepage URL: https://craft-mcp.YOUR_SUBDOMAIN.workers.dev

   • Authorization callback URL: https://craft-mcp.YOUR_SUBDOMAIN.workers.dev/callback

4. Click Register application

5. Copy the Client ID and generate a Client Secret

3. Create KV Namespace

# Create the KV namespace for OAuth tokens
wrangler kv namespace create OAUTH_KV

# Note the namespace ID from the output
# Update wrangler.toml with this ID

4. Configure Environment Variables

For Local Development

Create a .dev.vars file in the project root:

# Craft documents
CRAFT_DOCUMENTS={"My Document": "https://connect.craft.do/links/YOUR_LINK_ID/api/v1"}

# GitHub OAuth credentials
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

# Optional: Restrict access to specific GitHub users
ALLOWED_USERNAMES=username1,username2

Get Craft Document Link IDs:

1. Open your Craft document

2. Click Share → Enable API

3. Copy the link ID from the URL (e.g., AcHPMgNXYdR)

For Production

Set via Cloudflare Dashboard (Workers & Pages → Your Worker → Settings → Variables):

• CRAFT_DOCUMENTS - JSON mapping of document names to API URLs

• GITHUB_CLIENT_ID - Your GitHub OAuth Client ID

• GITHUB_CLIENT_SECRET - Your GitHub OAuth Client Secret (mark as encrypted)

• ALLOWED_USERNAMES - (Optional) Comma-separated list of allowed GitHub usernames

OR use Wrangler CLI:

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put CRAFT_DOCUMENTS

5. Update wrangler.toml

Replace YOUR_KV_NAMESPACE_ID_HERE with your actual KV namespace ID:

[[kv_namespaces]]
binding = "OAUTH_KV"
id = "your_actual_namespace_id"

6. Run Locally

npm run dev

Your MCP server will be available at http://localhost:8787/sse

7. Deploy to Cloudflare

Via GitHub (Recommended)

1. Connect your GitHub repo to Cloudflare (Workers & Pages → Create → Connect to Git)

2. Configure environment variables in the dashboard

3. Push changes to main branch - Cloudflare automatically deploys

Direct Deployment

npm run deploy

Note: Set environment variables in the dashboard first. The keep_vars = true setting ensures they won't be overwritten.

Connect to Claude Desktop

Edit your Claude Desktop config (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "craft": {
      "url": "https://craft-mcp.YOUR_SUBDOMAIN.workers.dev/sse"
    }
  }
}

For local development, use http://localhost:8787/sse

Authentication Flow:

1. Restart Claude Desktop

2. When you try to use Craft tools, you'll be redirected to GitHub

3. Authorize the application

4. You'll be redirected back and authentication will complete

5. Craft tools will become available

The OAuth flow is handled automatically by the MCP client.

Available Tools

• listDocuments - Show configured documents

• readDocument - Read document content with embedded IDs

• insertText - Insert markdown content into documents

• deleteText - Delete pages or headings

• search - Search within documents with regex support

• getCollectionItems - Retrieve items from Craft collections

• createCollectionItems - Add items to collections

• updateCollectionItems - Update existing collection items

See CLAUDE.md for detailed tool documentation and architecture information.

Development

# Install dependencies
npm install

# Run locally
npm run dev

# Type check
npm run type-check

# Lint and format
npm run lint:fix
npm run format

# Deploy to Cloudflare
npm run deploy

Project Structure

craft-mcp/
├── src/
│   └── index.ts          # MCP server implementation
├── docs/                 # API documentation
├── wrangler.toml         # Cloudflare Workers config (placeholders only)
├── .dev.vars            # Local env vars (gitignored, create this)
└── package.json

Security Notes

• OAuth Authentication: All access requires GitHub authentication

• User Whitelist: Use ALLOWED_USERNAMES to restrict access to specific GitHub users

• Document Link IDs: Provide full API access to your Craft documents - keep them private

• Environment Variables: Never commit real credentials or link IDs to version control

• KV Namespace: The OAUTH_KV namespace stores OAuth tokens and session state

• Keep .dev.vars and production environment variables secure

License

MIT