Skip to content
Back to search

firefly-iii-mcp

MCP Server for Firefly III

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/etnperlong--firefly-iii-mcp/badge.svg)](/listings/etnperlong--firefly-iii-mcp)

HTML

<a href="/listings/etnperlong--firefly-iii-mcp"><img src="/api/listings/etnperlong--firefly-iii-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.

1. Obtain a Firefly III Personal Access Token (PAT)

To allow the MCP server to interact with your Firefly III instance, you need to generate a Personal Access Token (PAT):

1. Log in to your Firefly III instance 2. Navigate to **Options > Profile > OAuth** 3. Under the "Personal access tokens" section, click on "Create new token" 4. Give your token a descriptive name (e.g., "MCP Server Token") 5. Click "Create" 6. **Important:** Copy the generated token immediately. You will not be able to see it again.

For more details, refer to the official Firefly III documentation on [Personal Access Tokens](https://docs.firefly-iii.org/how-to/firefly-iii/features/api/).

2. Configure the MCP Server

You need to provide the Firefly III PAT and your Firefly III instance URL to the MCP server. This can be done in several ways:

Request Headers (Recommended)

Provide these values in the headers of each request to the MCP server. This is generally the most secure method:

* `X-Firefly-III-Url`: Your Firefly III instance URL (e.g., `https://firefly.yourdomain.com`) * `Authorization`: The Personal Access Token, typically prefixed with `Bearer ` (e.g., `Bearer YOUR_FIREFLY_III_PAT`)

Please consult the documentation of the AI tool or client you are using for the exact header names it expects.

Query Parameters (Use with caution)

Alternatively, you can provide these values in the query parameters of each request to the MCP server:

* `baseUrl`: Your Firefly III instance URL * `pat`: Your Firefly III Personal Access Token

Please note that URLs, including query parameters, can be logged in various places, potentially exposing sensitive information.

Environment Variables (Primarily for self-hosting/local development)

Set the following environment variables before running the server:

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

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 · 255 lines

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

  1. # Firefly III MCP Server
  2. This is a Model Context Protocol (MCP) server for Firefly III, a free and open-source personal finance manager. Through this MCP server, users can leverage AI tools to manage their Firefly III accounts and transactions, creating AI assistants for personal finance and accounting.
  3. *[查看中文版](README_ZH.md)*
  4. ## Project Structure
  5. This project uses a Turborepo-managed monorepo structure, containing the following main packages:
  6. * **@firefly-iii-mcp/core** - Core functionality module providing the foundation for interacting with the Firefly III API
  7. * **@firefly-iii-mcp/local** - Command-line tool for running the MCP server locally
  8. * **@firefly-iii-mcp/cloudflare-worker** - Implementation for deployment to Cloudflare Workers
  9. * **@firefly-iii-mcp/server** - Express-based server implementation with Streamable HTTP and SSE support
  10. ## Features
  11. * Interact with Firefly III instances via AI
  12. * Programmatically manage accounts and transactions
  13. * Extensible toolset for various financial operations
  14. * Support for both local and cloud deployment
  15. * Compatible with the Model Context Protocol standard
  16. * Tool filtering via presets or custom tags to reduce token usage
  17. ## Prerequisites
  18. * A running [Firefly III](https://www.firefly-iii.org/) instance
  19. * A Cloudflare account if you plan to deploy using the "Deploy to Cloudflare" button
  20. ## Getting Started
  21. ### 1. Obtain a Firefly III Personal Access Token (PAT)
  22. To allow the MCP server to interact with your Firefly III instance, you need to generate a Personal Access Token (PAT):
  23. 1. Log in to your Firefly III instance
  24. 2. Navigate to **Options > Profile > OAuth**
  25. 3. Under the "Personal access tokens" section, click on "Create new token"
  26. 4. Give your token a descriptive name (e.g., "MCP Server Token")
  27. 5. Click "Create"
  28. 6. **Important:** Copy the generated token immediately. You will not be able to see it again.
  29. For more details, refer to the official Firefly III documentation on [Personal Access Tokens](https://docs.firefly-iii.org/how-to/firefly-iii/features/api/).
  30. ### 2. Configure the MCP Server
  31. You need to provide the Firefly III PAT and your Firefly III instance URL to the MCP server. This can be done in several ways:
  32. #### Request Headers (Recommended)
  33. Provide these values in the headers of each request to the MCP server. This is generally the most secure method:
  34. * `X-Firefly-III-Url`: Your Firefly III instance URL (e.g., `https://firefly.yourdomain.com`)
  35. * `Authorization`: The Personal Access Token, typically prefixed with `Bearer ` (e.g., `Bearer YOUR_FIREFLY_III_PAT`)
  36. Please consult the documentation of the AI tool or client you are using for the exact header names it expects.
  37. #### Query Parameters (Use with caution)
  38. Alternatively, you can provide these values in the query parameters of each request to the MCP server:
  39. * `baseUrl`: Your Firefly III instance URL
  40. * `pat`: Your Firefly III Personal Access Token
  41. Please note that URLs, including query parameters, can be logged in various places, potentially exposing sensitive information.
  42. #### Environment Variables (Primarily for self-hosting/local development)
  43. Set the following environment variables before running the server:
  44. ```bash
  45. FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
  46. FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
  47. # Optional: Filter tools using preset or custom tags
  48. FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
  49. # Or specify custom tool tags (overrides preset if both are set)
  50. FIREFLY_III_TOOLS="accounts,transactions,categories"
  51. ```
  52. ## Running the MCP Server
  53. ### Method 1: Local Mode
  54. This method is suitable for clients that support calling MCP tools via standard input/output (stdio), such as [Claude Desktop](https://claude.ai/download).
  55. Basic run command:
  56. ```bash
  57. npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL
  58. ```
  59. You can also filter the available tools to reduce token usage:
  60. ```bash
  61. # Using a preset
  62. npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget
  63. # Using custom tool tags
  64. npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories
  65. ```
  66. You can also refer to the [official tutorial](https://modelcontextprotocol.io/quickstart/user) for configuration in JSON format.
  67. ```json
  68. {
  69. "mcpServers": {
  70. "firefly-iii": {
  71. "command": "npx",
  72. "args": [
  73. "@firefly-iii-mcp/local",
  74. "--pat",
  75. "<Your Firefly III Personal Access Token>",
  76. "--baseUrl",
  77. "<Your Firefly III Base URL>",
  78. "--preset",
  79. "default"
  80. ]
  81. }
  82. }
  83. }
  84. ```
  85. ### Method 2: Express Server (Recommended for Web Apps)
  86. This method provides an HTTP-based server with Streamable HTTP and SSE support, making it ideal for web applications.
  87. #### As a Command-Line Tool
  88. ```bash
  89. npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL
  90. ```
  91. Command-line options:
  92. - `-p, --pat <token>` - Firefly III Personal Access Token
  93. - `-b, --baseUrl <url>` - Firefly III Base URL
  94. - `-P, --port <number>` - Port to listen on (default: 3000)
  95. - `-l, --logLevel <level>` - Log level: debug, info, warn, error (default: info)
  96. - `-s, --preset <name>` - Tool preset to use (default, full, basic, budget, reporting, admin, automation)
  97. - `-t, --tools <list>` - Comma-separated list of tool tags to enable
  98. #### As a Library
  99. ```bash
  100. npm install @firefly-iii-mcp/server
  101. ```
  102. Basic usage:
  103. ```typescript
  104. import { createServer } from '@firefly-iii-mcp/server';
  105. const server = createServer({
  106. port: 3000,
  107. pat: process.env.FIREFLY_III_PAT,
  108. baseUrl: process.env.FIREFLY_III_BASE_URL,
  109. enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
  110. });
  111. server.start().then(() => {
  112. console.log('MCP Server is running on http://localhost:3000');
  113. });
  114. ```
  115. For more details, see the [@firefly-iii-mcp/server documentation](packages/server/README.md).
  116. ### Method 3: Deploy to Cloudflare Workers (Recommended for Production)
  117. You can easily deploy this MCP server to Cloudflare Workers using the button below:
  118. [![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/etnperlong/firefly-iii-mcp/tree/main/packages/cloudflare-worker)
  119. **Note:** After deploying, you will need to configure the environment variables in your Cloudflare Worker's settings:
  120. 1. Go to your Cloudflare dashboard
  121. 2. Navigate to Workers & Pages
  122. 3. Select your deployed Worker
  123. 4. Go to Settings > Variables
  124. 5. Add the following variables:
  125. - Required: `FIREFLY_III_BASE_URL` and `FIREFLY_III_PAT`
  126. - Optional: `FIREFLY_III_PRESET` or `FIREFLY_III_TOOLS`
  127. ### Method 4: Run Locally from Source
  128. > [!NOTE]
  129. > For production use, it is recommended to use the NPM package or deploy to Cloudflare Workers.
  130. 1. Clone the repository:
  131. ```bash
  132. git clone https://github.com/etnperlong/firefly-iii-mcp.git
  133. cd firefly-iii-mcp
  134. ```
  135. 2. Install dependencies:
  136. ```bash
  137. npm install
  138. ```
  139. 3. Create a `.env` file:
  140. ```
  141. FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
  142. FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
  143. # Optional: Filter tools
  144. FIREFLY_III_PRESET="default"
  145. # Or
  146. FIREFLY_III_TOOLS="accounts,transactions,categories"
  147. ```
  148. 4. Build the project:
  149. ```bash
  150. npm run build
  151. ```
  152. 5. Start the development server:
  153. ```bash
  154. npm run dev
  155. ```
  156. ## Tool Filtering Options
  157. You can filter which tools are exposed to the MCP client to reduce token usage and focus on specific functionality:
  158. ### Available Presets
  159. - `default`: Basic tools for everyday use (accounts, bills, categories, tags, transactions, search, summary)
  160. - `full`: All available tools
  161. - `basic`: Core financial management tools
  162. - `budget`: Budget-focused tools
  163. - `reporting`: Reporting and analysis tools
  164. - `admin`: Administration tools
  165. - `automation`: Automation-related tools
  166. ## Development Guide
  167. This project uses [Turborepo](https://turbo.build/) to manage the monorepo workflow and [Changesets](https://github.com/changesets/changesets) for versioning and publishing.
  168. ### Common Commands
  169. - Build all packages: `npm run build`
  170. - Build specific packages: `npm run build:core` or `npm run build:local`
  171. - Clean build artifacts: `npm run clean`
  172. - Development mode: `npm run dev`
  173. - Publish packages: `npm run publish-packages`
  174. For detailed development guidelines, please refer to the [contribution guide](CONTRIBUTING.md).
  175. ## Acknowledgements
  176. This project utilizes and modifies generation scripts from [harsha-iiiv/openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator). Many thanks to the original authors for their work.
  177. ## Contributing
  178. Contributions are welcome! This project uses Turborepo to manage the monorepo workflow. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute.
  179. ## License
  180. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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