This MCP server lets you manage Craft documents and collections from an AI-assisted client. It provides read/write/search/delete capabilities across multiple Craft documents, supports collections, and authenticates access via GitHub. Hosted on Cloudflare Workers, it enables serverless operation with secure OAuth flow and durable state management.

How to use

You connect your MCP client to the Craft MCP Server using the remote URL provided by the server. Once connected, you can list your configured Craft documents, read and insert content, manage headings and pages, search across documents, and work with Craft collections. Authentication is required via GitHub, and only whitelisted users (if configured) can access the server.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

Clone the project and install dependencies:

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

Create a GitHub OAuth App to enable user authentication.

Steps to create the OAuth app and obtain credentials are included in your setup process. After creating the app, you will have a Client ID and a Client Secret to configure the server.

Create a KV namespace for OAuth tokens (used for session state):

wrangler kv namespace create OAUTH_KV

Note the namespace ID from the output and update wrangler.toml accordingly.

Configure environment variables for local development. Create a .dev.vars file in the project root with the following content:

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

## Production configuration and deployment

Set environment variables in the hosting dashboard (or via secret management) before running or deploying. The following variables are required for production use:

CRAFT\_DOCUMENTS should be a JSON mapping of document names to their API URLs. GITHUB\_CLIENT\_ID and GITHUB\_CLIENT\_SECRET are the OAuth credentials. ALLOWED\_USERNAMES is an optional whitelist.

If you prefer using the Wrangler CLI for secrets, you can set them with these commands:

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

## Run locally

Start the server in development mode. The local MCP server will be available at the designated local URL.

npm run dev

## Deploy to Cloudflare

You can deploy via GitHub integration with Cloudflare or run a direct deployment command.

Direct deployment (after you have configured environment variables in the dashboard):

npm run deploy

## Connect to Claude Desktop

Configure Claude Desktop to point to the MCP server URL. In Claude Desktop, go to Settings → Developer → Edit Config and add the Craft MCP server URL.

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

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

Security and access control

All access requires GitHub authentication. You can restrict access to specific users by listing them in ALLOWED_USERNAMES. Keep Craft document link IDs private and do not expose real credentials in version control.

Notes on development and structure

Project structure includes a TypeScript MCP server implementation and a docs folder for API references. The server runs as a Cloudflare Worker with Durable Objects for state.

Available tools

listDocuments

Show configured Craft documents added to the MCP server.

readDocument

Read content from a Craft document with embedded IDs, enabling you to see structure and content.

insertText

Insert Markdown content into a Craft document at the desired location.

deleteText

Delete pages or headings within a Craft document.

search

Search across documents with support for regex patterns.

getCollectionItems

Retrieve items from Craft collections.

createCollectionItems

Add new items to Craft collections.

updateCollectionItems

Update existing items within Craft collections.