Skip to content
Back to search

mcp

Frappe MCP allows Frappe apps to function as MCP servers

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/frappe--mcp/badge.svg)](/listings/frappe--mcp)

HTML

<a href="/listings/frappe--mcp"><img src="/api/listings/frappe--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using PIP:

pip install frappe-mcp

Using UV:

uv add frappe-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 425 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Frappe MCP
  2. > [!WARNING]
  3. >
  4. > **This app is deprecated.**
  5. >
  6. > Frappe Framework now has a built-in MCP server. Use the built-in MCP server
  7. > for new projects, and move existing projects to it. This app will not get new
  8. > features.
  9. >
  10. > Refer to the [Frappe MCP guide](https://docs.frappe.io/framework/guides-integration/mcp).
  11. Frappe MCP allows your Frappe Framework app to function as a [Streamable HTTP MCP
  12. server](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http).
  13. ```python
  14. # app/app/mcp.py
  15. import frappe_mcp
  16. mcp = frappe_mcp.MCP("todo-mcp")
  17. @mcp.tool()
  18. def fetch_todos(username: str): ...
  19. @mcp.tool()
  20. def mark_done(name: str): ...
  21. # MCP endpoint at: http://<BASE_URL>/api/method/app.mcp.handle_mcp
  22. @mcp.register()
  23. def handle_mcp(): ...
  24. ```
  25. > [!NOTE]
  26. >
  27. > **Why not use the official Python SDK?**
  28. >
  29. > The official Python SDK only supports async Python, i.e. it assumes that your
  30. > server is an ASGI server.
  31. >
  32. > Frappe Framework is not async, it makes use of Werkzeug, a WSGI server, and so
  33. > a from scratch implementation was needed.
  34. > [!IMPORTANT]
  35. >
  36. > Frappe MCP is in a highly experimental state, there will be bugs, breaking
  37. > changes and large updates. Mostly without notice.
  38. _On GitHub, click the Index button on the top right to view the index._
  39. ## Installation
  40. Using PIP:
  41. ```bash
  42. pip install frappe-mcp
  43. ```
  44. Using UV:
  45. ```bash
  46. uv add frappe-mcp
  47. ```
  48. ## Limitations
  49. Frappe MCP is yet in its infancy, as of now it **only supports** Tools.
  50. Remaining server features such as resources, prompts, tool streaming using SSE
  51. will be added as needed.
  52. ## Auth
  53. If you are using a version of the Framework having the OAuth2 updates
  54. ([frappe#33188](https://github.com/frappe/frappe/pull/33188)) then using Frappe
  55. MCP with it should be pretty straight forward. You can view this video to check
  56. out how to set up Auth on the MCP Inspector.
  57. https://github.com/user-attachments/assets/a1783a36-7bea-4361-8c7b-bdbb9789877b
  58. If your version does not contain these updates, you will have to register an
  59. OAuth Client on your Framework instance for the MCP client. You can check the
  60. [docs](https://docs.frappe.io/framework/oauth2) for this.
  61. ## Documentation
  62. Frappe MCP is fairly straightforward to use. Most of the MCP specific heavy
  63. lifting is handled for you.
  64. ### Basic Usage
  65. To use `frappe-mcp` you first create an instance of the `mcp` object:
  66. ```python
  67. # app/app/mcp.py (same dir as hooks.py)
  68. import frappe_mcp
  69. mcp = frappe_mcp.MCP("your-app-mcp")
  70. ```
  71. Each instance of an `MCP` object can be used to register a single MCP endpoint.
  72. You can create multiple of these objects if you need to serve multiple MCP
  73. endpoints for instance to group functionality.
  74. #### Register tools with `@mcp.tool`
  75. You use the instaniated object i.e. `mcp` to register tools:
  76. ```python
  77. # app/app/tools/tools.py
  78. from app.mcp import mcp
  79. @mcp.tool()
  80. def tool_name(a: int, b: str):
  81. """Description of what the tool does
  82. Args:
  83. a: Description for arg `a`.
  84. b: Description for arg `b`.
  85. """
  86. ... # tool body
  87. return value
  88. ```
  89. > [!TIP]
  90. >
  91. > Using Google style docstrings and type annotations like in the example above
  92. > allows Frappe MCP to extract the `inputSchema` for the tool without any additional
  93. > configuration.
  94. If needed, you can manually provide the `inputSchema` and other meta data like annotations.
  95. Check the [Tools](#tools) section for more details.
  96. #### Register endpoint using `@mcp.register`
  97. You use the instantiated object to mark a function as the _entry point_ to your
  98. MCP server, i.e. the function endpoint will be where your MCP server is served
  99. from.
  100. ```python
  101. # app/app/mcp.py
  102. @mcp.register()
  103. def handle_mcp():
  104. import app.tools.tools # ensures that your tools are registered
  105. ```
  106. Once this is done, your MCP server should be serving at the REST endpoint for
  107. the method ([docs](https://docs.frappe.io/framework/user/en/api/rest#remote-method-calls)).
  108. In this case the endpoint when running locally would be:
  109. ```
  110. http://<SITE_NAME:PORT>/api/method/app.mcp.handle_mcp
  111. ```
  112. > [!WARNING]
  113. >
  114. > The function body's **only purpose is to import files containing your tools**.
  115. > If this is not done your tools will not be loaded as Frappe MCP does not know where
  116. > your tools are located.
  117. >
  118. > If your tools are in the same file, or have been imported globally, you can
  119. > leave the function body empty.
  120. ### Tools
  121. You can register tools, in the following ways:
  122. 1. Using the `@mcp.tool` decorator
  123. 2. Using the `mcp.add_tool` method
  124. #### `@mcp.tool` decorator
  125. The `@mcp.tool` decorator registers a function as a tool that can be used by an LLM.
  126. The decorator accepts the following optional arguments:
  127. - `name` (optional `str`): The name of the tool. If not provided, the function's `__name__` will be used.
  128. - `description` (optional `str`): A description of what the tool does. If not provided, it will be extracted from the function's docstring.
  129. - `input_schema` (optional `dict`): The JSON schema for the tool's input. If not provided, it will be inferred from the function's signature and docstring.
  130. - `use_entire_docstring` (optional `bool`): If `True`, the entire docstring will be used as the tool's description. Otherwise, only the first section is used (i.e. no `Args`). Defaults to `False`.
  131. - `annotations` (optional `dict`): Additional context about the tool, such as validation information or examples of how to use it. This should be a dictionary conforming to the `ToolAnnotations` `TypedDict` structure.
  132. **Example:**
  133. ```python
  134. from frappe_mcp import ToolAnnotations, MCP
  135. mcp = MCP()
  136. annotations = ToolAnnotations(
  137. title="Get Current Weather",
  138. readOnlyHint=True,
  139. )
  140. @mcp.tool(annotations=annotations)
  141. def get_current_weather(location: str, unit: str = "celsius"):
  142. '''Get the current weather in a given location.'''
  143. # ... implementation ...
  144. ```
  145. #### `mcp.add_tool` method
  146. The `mcp.add_tool` method allows manually defining a tool, serving as an alternative to the `@mcp.tool` decorator.
  147. It takes a `Tool` object as an arg.
  148. **Example:**
  149. ```python
  150. from frappe_mcp import Tool, MCP
  151. mcp = MCP()
  152. def get_current_weather(location: str, unit: str = "celsius"):
  153. '''Get the current weather in a given location.'''
  154. # ... implementation ...
  155. # Create a tool object
  156. weather_tool = Tool(
  157. name="get_current_weather",
  158. description="...",
  159. input_schema={'type':'object', 'properties':{ ... }},
  160. output_schema=None,
  161. annotations=None,
  162. fn=get_current_weather,
  163. )
  164. # Add the tool to the MCP instance
  165. mcp.add_tool(weather_tool)
  166. ```
  167. #### Tool Annotations
  168. The `ToolAnnotations` can be used to provide additional tool annotations
  169. defined by the MCP spec
  170. ([reference](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)).
  171. ```python
  172. class ToolAnnotations(TypedDict, total=False):
  173. title: str | None
  174. readOnlyHint: bool | None
  175. destructiveHint: bool | None
  176. idempotentHint: bool | None
  177. openWorldHint: bool | None
  178. ```
  179. #### Tool Definition
  180. The `Tool` object that is used when manually defining and registering a tool
  181. using `mcp.add_tool`.
  182. ```python
  183. class Tool(TypedDict):
  184. name: str
  185. description: str
  186. input_schema: dict[str, Any]
  187. output_schema: dict[str, Any] | None
  188. annotations: ToolAnnotations | None
  189. fn: Callable
  190. ```
  191. #### Input Schema
  192. Input schema refers to the [JSON Schema](https://json-schema.org/understanding-json-schema/reference/type) definition that describes a tool's parameters.
  193. The following tool:
  194. ```python
  195. @mcp.tool()
  196. def tool_name(a: int, b: str = "default"):
  197. """Description of what the tool does
  198. Args:
  199. a: Description for arg `a`.
  200. b: Description for arg `b`.
  201. """
  202. ... # tool body
  203. return value
  204. ```
  205. will have this input schema:
  206. ```json
  207. {
  208. "type": "object",
  209. "properties": {
  210. "a": {
  211. "type": "integer",
  212. "description": "Description for arg `a`."
  213. },
  214. "b": {
  215. "type": "string",
  216. "description": "Description for arg `b`."
  217. }
  218. },
  219. "required": ["a"]
  220. }
  221. ```
  222. This input schema is generated from the tool body automatically when using the
  223. decorator.
  224. ### MCP
  225. The `MCP` class is the main class for creating an MCP server.
  226. This class orchestrates the handling of JSON-RPC requests, manages a registry of
  227. available tools, and integrates with a WSGI server (like Frappe Framework) to
  228. expose MCP functionality.
  229. In a Frappe application, you would typically create a single instance of this
  230. class and use the `@mcp.register()` decorator on an API endpoint. Tools can be
  231. added using the `@mcp.tool()` decorator.
  232. For use in other Werkzeug-based servers, you can use the `mcp.handle()` method
  233. directly.
  234. #### `mcp.register` decorator
  235. This decorator is used in Frappe applications to designate a function as the
  236. entry point for MCP requests. It wraps the function with the necessary logic to
  237. handle JSON-RPC messages, including initializing the tool registry and routing
  238. requests to the appropriate handlers.
  239. The decorator accepts the following optional arguments:
  240. - `allow_guest` (optional `bool`): If `True`, allows unauthenticated access to the endpoint. Defaults to `False`.
  241. - `xss_safe` (optional `bool`): If `True`, response will not be sanitized for XSS. Defaults to `False`.
  242. **Example:**
  243. ```python
  244. # In app/mcp.py
  245. from frappe_mcp import MCP
  246. mcp = MCP(name="my-mcp-server")
  247. @mcp.register()
  248. def handle_mcp():
  249. '''The entry point for MCP requests.'''
  250. # This function body is executed before request handling.
  251. # It's a good place to import modules that register tools.
  252. import app.tools
  253. ```
  254. #### `mcp.handle` method
  255. This method directly processes a `werkzeug.Request` and returns a
  256. `werkzeug.Response`. It's the core request handling logic.
  257. This method can be used to integrate the MCP server into **any Werkzeug-based application**
  258. i.e. even if you're not using Frappe Framework, you can use this to handle MCP
  259. endpoints in your server.
  260. It accepts the following arguments:
  261. - `request`: The `werkzeug.Request` object containing the MCP request.
  262. - `response`: A `werkzeug.Response` object to be populated with the MCP response.
  263. It returns the populated `werkzeug.Response` object.
  264. ## CLI
  265. Frappe MCP comes with a handy CLI tool to help you verify that your MCP server is set up correctly.
  266. <img width="436" alt="check" src="https://github.com/user-attachments/assets/a8e1481a-5388-4976-9728-404677381a07" />
  267. Its `check` command inspects your Frappe apps to ensure that `frappe_mcp` is being used correctly. This is also the default command, so you can run it with `frappe-mcp` or `frappe-mcp check`.
  268. It performs the following checks:
  269. - Verifies that it's running within a Frappe environment.
  270. - Finds all apps that are potentially using `frappe_mcp`.
  271. - For each app, it discovers MCP handlers.
  272. - It then checks the handlers and their tools for correctness.
  273. **Options:**
  274. - `--app`, `-a`': Check only a specific app.
  275. - `--verbose`, `-v`: Show detailed information such as the input schema.
  276. **Usage:**
  277. ```bash
  278. # After installing frappe-mcp and using it in your app
  279. # In your frappe bench dir so that you can use the cli
  280. source ./env/bin/activate
  281. # Check all apps that might be using Frappe MCP
  282. frappe-mcp
  283. # Check specific app with verbose output
  284. frappe-mcp check --app app_name --verbose
  285. ```
  286. ## Testing against Inspector
  287. You can use the official
  288. [inspector](https://github.com/modelcontextprotocol/inspector) tool to verify if
  289. your MCP endpoints are being served correctly.
  290. ![inspector](https://github.com/user-attachments/assets/64e13ed4-0170-48b4-8b35-530e0f713a29)
  291. Make sure to:
  292. 1. Set **Transport** to **Streamable HTTP**.
  293. 2. Set **URL** to your MCP endpoint (you can use the CLI command `frappe-mcp check` to get it).
  294. 3. Navigate to Auth Settings then click on **Quick OAuth Flow**
  295. After this you'll be prompted to login and authorize the client after which you
  296. can use it to test out your MCP server.
  297. > [!NOTE]
  298. >
  299. > You may skip the final step by setting the `allow_guests` flag, i.e:
  300. >
  301. > ```python
  302. > @mcp.register(allow_guests=True)
  303. > def handle_mcp(): ...
  304. > ```
  305. >
  306. > **This bypasses auth, so make sure you don't do this in production.**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.