Firefly III MCP Server

Getting Started

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.

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"

Running the MCP Server

Method 1: Local Mode

This method is suitable for clients that support calling MCP tools via standard input/output (stdio), such as Claude Desktop.

Basic run command:

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

You can also refer to the official tutorial for configuration in JSON format.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>"
      ]
    }
  }
}

Method 2: Deploy to Cloudflare Workers (Recommended for Production)

You can easily deploy this MCP server to Cloudflare Workers using the button below:

Note: After deploying, you will need to configure the FIREFLY_III_BASE_URL and FIREFLY_III_PAT environment variables in your Cloudflare Worker's settings:

1. Go to your Cloudflare dashboard
2. Navigate to Workers & Pages
3. Select your deployed Worker
4. Go to Settings > Variables
5. Add FIREFLY_III_BASE_URL and FIREFLY_III_PAT as secret variables

Method 3: Run Locally from Source

1. Clone the repository:

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp
   

2. Install dependencies:

   npm install
   

3. Create a .env file:

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   

4. Build the project:

   npm run build
   

5. Start the development server:

   npm run dev
   

Development Guide

This project uses Turborepo to manage the monorepo workflow and Changesets for versioning and publishing.

Common Commands

• Build all packages: npm run build
• Build specific packages: npm run build:core or npm run build:local
• Clean build artifacts: npm run clean
• Development mode: npm run dev
• Publish packages: npm run publish-packages

Acknowledgements

This project utilizes and modifies generation scripts from harsha-iiiv/openapi-mcp-generator. Many thanks to the original authors for their work.

This project is licensed under the MIT License.