MCP server with OAuth for the Frappe Framework
mcpserver
mcpserver turns a Frappe site into a remote MCP server that Claude and
other AI clients can sign in to with OAuth. It serves curated, task-level tools that your apps register,
for example "get customer profile" or "log a meeting note", instead of raw document access. Every tool call
runs as the signed-in user, with that user's permissions.
- One endpoint. Streamable HTTP (protocol 2025-06-18, 2025-03-26 and 2024-11-05) with plain JSON
responses at
/api/method/mcpserver.mcp.endpoint. - OAuth sign-in for MCP clients. Uses Frappe's OAuth 2 provider with discovery metadata and dynamic client registration, and makes it stricter: public clients only, loopback or allowlisted redirect URIs, PKCE S256, plain-text client names, refresh token rotation with reuse detection, tokens bound to the MCP endpoint, a registration rate limit and a daily cleanup of stale clients and tokens.
- Tool registry for apps. Any installed app can add its own tools through the
mcp_toolshook. - Safe tool calls. Arguments are checked against the tool's schema. A failed call rolls back everything it wrote, including commit callbacks, and unexpected errors never leak tracebacks.
Installation
bench get-app https://github.com/EffizienzAgent/mcpserver --branch version-16
bench --site <site> install-app mcpserver
Compatibility: Frappe v16. The version-16 branch always points to the latest release; tagged releases
and the changelog are on the releases page.
The app ships no tools of its own; install an app that registers tools through the
mcp_tools hook, or write your own (see docs/tools.md). OAuth discovery metadata and dynamic client registration must be on in OAuth
Settings, as they are by default. The app fills in these settings only where none are stored and never
changes a stored value.
Connect a client
claude mcp add --scope user --transport http mysite https://<site>/api/method/mcpserver.mcp.endpoint
Claude Code opens the browser on first use. Sign in to the site and click Allow. For claude.ai, Claude Desktop, other MCP clients and API keys, see docs/clients.md.
Documentation
- docs/clients.md: connecting Claude and other MCP clients, revoking access.
- docs/tools.md: adding tools from your app, server info and instructions hooks.
- docs/builtin-mcp.md: how this relates to Frappe's built-in MCP server.
- docs/oauth.md: how sign-in works and what the app enforces.
Frappe's built-in MCP server
Frappe v16 ships a generic MCP server at /api/v2/mcp. Its tools create, update and delete documents of
any doctype the user may access and call any whitelisted method. mcpserver complements it: a separate
endpoint with OAuth sign-in for Claude and only the curated tools your apps register.
If agents should be limited to curated tools, turn the built-in server off: uncheck System Settings >
AI Agents > Enable MCP, or set disable_mcp_server in the site config. mcpserver never changes this
setting itself; it prints a hint on install while the built-in server is on. See
docs/builtin-mcp.md.
Development
bench --site <site> set-config allow_tests true
bench --site <site> run-tests --app mcpserver
CI runs the tests on a Frappe v16 bench pinned in .github/versions.env.
Professional setup & support
Need help setting this up or integrating it into your Frappe stack? Write to oss@effizienzagent.de (English or German). German-speaking SMEs: see mittelstandshub.de.
License
MIT, see license.txt.