IMON Framer Chat MCP

Private remote MCP gateway for connecting ChatGPT to one configured Framer project. It exposes focused read tools, controlled write tools, and separate publishing tools over /mcp.

Architecture

ChatGPT / MCP client
  -> HTTPS /mcp
  -> framer-chat-mcp
  -> framer-api
  -> one server-configured Framer project

The server is tool-only. There is no widget UI in v1. The Framer project URL and API key are server-side configuration only; tool input cannot switch projects.

Security Model

• Production must use authentication. MCP_AUTH_MODE=none is rejected when NODE_ENV=production.
• oauth-jwt validates JWT issuer, audience, expiry, and signature through JWKS.
• bearer is available for private/dev deployments and MCP Inspector testing.
• Writes require FRAMER_WRITES_ENABLED=true.
• Publishing and production deploy require FRAMER_PUBLISH_ENABLED=true.
• No tool publishes as a side effect of an edit.
• Framer content is untrusted data and never changes server configuration.

Local Setup

npm ci
cp .env.example .env.local
npm run typecheck
npm test
npm run build
npm run smoke:mcp

For local development without auth:

MCP_AUTH_MODE=none npm run dev

Health endpoints:

curl http://localhost:8787/healthz
curl http://localhost:8787/readyz

Environment Variables

Required for live Framer tools:

FRAMER_PROJECT_URL=
FRAMER_API_KEY=
EXPECTED_FRAMER_PROJECT_NAME=

Auth:

MCP_AUTH_MODE=none|bearer|oauth-jwt
MCP_ACCESS_TOKEN=
OAUTH_ISSUER=
OAUTH_AUDIENCE=
OAUTH_JWKS_URL=
ALLOWED_USER_EMAIL=
ALLOWED_SUBJECTS=

Controls:

FRAMER_WRITES_ENABLED=false
FRAMER_PUBLISH_ENABLED=false

Framer Credential Setup

From Framer documentation and framer-api README:

1. Open the Framer project.
2. Open settings, for example with Cmd+K and "open settings".
3. Find the API Keys section.
4. Create a Server API key.
5. Store it only in Vercel or local ignored env, never in Git.

Commands

npm run lint
npm run typecheck
npm test
npm run build
npm run doctor
npm run smoke:mcp
npm run live:read
npm run security:scan

live:read requires Framer env vars and writes private output only under .local/.

Vercel Deploy

This repo includes api/index.ts and vercel.json for Node.js 24 Vercel Functions.

vercel link
vercel env add FRAMER_PROJECT_URL production
vercel env add FRAMER_API_KEY production
vercel env add MCP_AUTH_MODE production
vercel env add OAUTH_ISSUER production
vercel env add OAUTH_AUDIENCE production
vercel env add OAUTH_JWKS_URL production
vercel deploy --prod

If Framer credentials are not set, /healthz still works and Framer tools return CONFIGURATION_ERROR.

ChatGPT Setup

See docs/CHATGPT-SETUP.md.

Use the deployed MCP URL:

https://<deployment>/mcp

Smoke prompts:

Use IMON Framer and show me the current project information.
List all pages in the connected Framer project. Do not make changes.
Inspect the homepage structure and summarize its top-level sections. Do not modify anything.
List the CMS collections and their schemas.
Show whether there are unpublished changes.

Limitations

• No public App Directory submission is prepared in v1.
• OAuth provider setup is code-supported but provider tenant/app creation is external.
• Live Framer tests require a real Framer Server API key.
• Broad canvas edits use official framer.agent.applyChanges DSL behind FRAMER_WRITES_ENABLED; they are not arbitrary JavaScript execution.