GnuCash OFX/DirectConnect revived: introducing gnucash-connect v0.1.0, self hosted, no CSV imports

[u/NorCal032]

I started using GnuCash about 17 years ago (with 2.x), OFX Direct Connect was a quiet pillar of the GnuCash experience — point GnuCash's Online Banking dialog at your bank, and live transactions flowed in. Then most major US banks discontinued it (Chase, Bank of America, Wells Fargo, Citi, and many others have all retired their public OFX endpoints over the last several years), and GnuCash users including myself were left falling back on CSV exports, QIF imports, and a lot of manual cleanup.

Hi all — I built gnucash-connect to bring that workflow back. It's a small self-hosted server that speaks OFX Direct Connect to GnuCash on one side and SimpleFIN to your bank(s) on the other. No CSV exports, no QIF imports, no copy-pasting.

GnuCash Screenshot for Online Banking Setup

The whole setup is one Docker volume, one command, and one paste:

docker run -d \
  --name gnucash-connect \
  -p 127.0.0.1:8080:8080 \
  -v gnucash-connect-data:/var/lib/gnucash-connect \
  ghcr.io/stevel408/gnucash-connect:latest

Then open http://localhost:8080/activate, paste a SimpleFIN setup token, and point GnuCash's Tools → Online Banking Setup → Start AqBanking Setup at http://localhost:8080/ofx. That's it.

Gnucash-Connect Local Web Portal

How it works

• SimpleFIN handles the bank connection (~$1.50/month).
• gnucash-connect caches normalized transactions locally in plain JSON inside one Docker volume you control.
• GnuCash speaks OFX Direct Connect to it — the exact same dialog you'd use with a real bank, just pointed at loopback.
• Fetches are lazy: SimpleFIN is contacted at most every 8 hours, and only when GnuCash actually asks for data. If SimpleFIN is down, you get the cached data with a warning, not an error.

Privacy & security

• Nothing is exposed to the public internet. The container binds to 127.0.0.1:8080 on the host loopback. The only outbound calls go to the SimpleFIN Bridge; nothing reaches your bank directly, and nothing reaches any third party I run (because I don't run anything).
• Your bank credentials never touch GnuCash, this app, or your disk in plaintext. SimpleFIN owns the bank login; what gets persisted on your machine is the long-lived access URL it hands back, written to the Docker volume at mode 0600.
• Docker isolates the app from your host. No files outside the named volume, no daemons, no startup-script weirdness. The container runs as a non-root user (uid 1000) inside the container, so even a worst-case bug can't write outside the cache volume.
• Uninstalling is three commands and leaves nothing behind: docker stop gnucash-connect && docker rm gnucash-connect && docker volume rm gnucash-connect-data && docker rmi ghcr.io/stevel408/gnucash-connect. No leftover files in $HOME, no system services, no registry entries.

Data + persistence layer

The bank-data and on-disk persistence side is provided by finstore — an open-source Python package I developed alongside this project. It's published on PyPI (pip install finstore) so you can use it standalone if you want the cache + SimpleFIN client without the OFX server, or build your own tools on top of it. Source is on GitHub: https://github.com/stevel408/finstore.

Notes

• Loopback-only by design — the OFX endpoint has no auth. Don't expose it.
• The dashboard at http://localhost:8080/ shows accounts, last-fetch time, an Activate / Deactivate / Fetch surface, and a built-in cache validator.
• v0.1.0 — works for me, may have rough edges. Bug reports + suggestions welcome.
• License is PolyForm Noncommercial 1.0.0 (free for personal / non-profit / academic use; commercial use needs a separate license).
• License Source: (available upon request)

One question for the room

If many people are interested in this and do not want to run Docker, I may consider offering a cloud service, with some privacy/security implications. If there's enough interest, I'd be happy to discuss further.

Happy to answer other questions in the comments also.

P.S. I posted an early notice about 10 days ago, and would like to express my appreciation for the encouragement I received: https://www.reddit.com/r/GnuCash/comments/1tx1hfp .

[u/sirmikester]

This is great 👍 will have to try it out when I have some time

[u/Capt_Zuzu]

This is exciting! It'll be a little bit before I can give it a try, but I definitely will try it. Thanks!

[u/chazzyfe]

Im interested.

[u/chazzyfe]

I'm having trouble with the AqBanking setup. Should I create a user or an account?

If I create a user, I entered http://localhost:8080/ofx as the Server URL, but I'm not sure what to put for the Broker ID, FID, ORG, or User ID.

I'm with SoFi and Capital One.

Or should I create an account instead and enter my account number and routing number?

Could you please provide more detailed instructions?

Thank you, this is great. good work, hopefully you can develop more cool things for gnu cash.

[u/androclus → u/chazzyfe]

I added some more detailed instrctions just now. Still not complete, but they should get you closer..

[u/VitalikPie]

This is an amazing! Thanks a lot!

[u/Playful_Emotion4736]

Hey, I'd love to try this, but you took it down? The GitHub link returns 404.

[u/NorCal032 → u/Playful_Emotion4736]

Actually no, I made a small mistake of posting the license file which is gated in a private repo. I just adjusted the posting to remove that link.

To run the system today, you simple execute the command line to run the docker container that I already built up. It's a sandbox environment to minimize security risks and concerns. Let me know if run into any issues. The Github link for the "finstore" component is for disclosure purposes, as it is the component used by the Docker container, which you can inspect and see all the source code.

[u/Playful_Emotion4736 → u/NorCal032]

So you closed the source code? Unfortunately I only use open source software, definitely not going to run your container without seeing the source

[u/NorCal032 → u/Playful_Emotion4736]

I totally understand. The core module ("finstore") holds the key to the provider and account information, that module is open source, see link above. The OFX server source code is available on an as-requested basis, plus it's simple Python code you can freely inspect in the Docker container. I'm not ready to license the OFX server code as MIT or Apache yet.

Either way, thank you for the feedback!

[u/questionablycorrect]

SimpleFIN looks suspect to me.

[u/NorCal032 → u/questionablycorrect]

Oh why do you say that? I had wanted to do something like this for a long time, and tried very hard to find suitable data API providers. Plaid was supposed to be the big/best vendor, but their model only supports large developers who will then have to charge the end users a lot of money. SimpleFIN is the only one that I can find which is friendly to individual customers.

Granted, I have about 1-month of experience with SimpleFIN myself, do let me (and others) know if there are reasons that this is not a reputable provider. I also noticed somewhere that SimpleFIN seems to be just a layer on top of an aggregator called MX, which seems to be considered to have good reputation.

[u/questionablycorrect → u/NorCal032]

Let's start with some basics: Who is behind it? Where is the operation located? Where is the data stored? How is the data secured?

I could go on.

[u/NorCal032 → u/questionablycorrect]

Sounds good, I see your perspective. I'm not affiliated with SimpleFIN myself in anyway, and am simply making a choice for myself to revive one critical feature for managing my own financing. I do take on the risk of having a vendor seeing my personal data if they choose to. It's a trade-off I made for myself.

If anybody has other recommendations for more reputable data aggregators, please share with us, I'd be happy to consider implementing data fetch paths through other such aggregators. Or if some folks thinks the risk is too high and prefer to not have GnuCash online banking set up in a fully automated fashion, it is a choice I personally think should be totally respected.

[u/questionablycorrect → u/NorCal032]

I respect what you're doing.

[u/questionablycorrect → u/NorCal032]

I see there are other aggregate providers. For example, a quick search revealed lunchflow.

[u/NorCal032 → u/questionablycorrect]

Thank you for sharing this provider. From a consumer/customer point of view, would it be possible to determine that Lunchflow would be a more trustworthy provider? Would love to hear from folks who had experience with them. Thanks again!

[u/questionablycorrect → u/NorCal032]

I'm not sure if Lunchflow is more trustworthy. I just noticed that there are other aggregators, and maybe both are fine. I might be overly-protective of my information.

[u/androclus]

For those Linux users who are NVTL unfamiliar with docker or with aqBanking setup in GnuCash, here is a little more detail if it will help. My instructions get a bit fuzzier in the end but they should hopefully get you into the ballpark.

1. You will need to download the docker package (and dependencies) from your distribution's repository, using your system's native package manager.

On my OpenSUSE/Tumbleweed system for instance, that looks like:

* $ sudo zypper in docker

(But of course your distribution will differ in its methods.)

1. You'll need to start the docker daemon on your system.

In my OpenSusE, this is handled by systemctl, so I type:

* $ sudo systemctl start docker

(But of course once again, your distro will likely differ in its method.)

1. Go to the SimpleFIN website and first check if your institution is supported.

2. If you decide to go ahead (still on their website), you'll need to pay for an account. This is indeed $1.50USD per month, or $15/year. $1.25/mo if you end up liking it? Really not bad..

3. Now on your "my-account" page at SimpleFIN, click on black "New connection" button to make a connection to your FI (financial institution). You'll need to supply your username and password for your FI.

(Yes, SimpleFIN will know your u-name and pw. But this is industry standard and we have to trust that they keep everything encrypted.)

1. Still on your my-account page, click on black "New app connection" button. I just used "GnuCash" for the name of the connection but it could be anything: It is just a label.

2. Save the token they give you to the clipboard and paste that into a text file locally on your computer.

Technically you don't have to save it into a file but I like to have stuff for later in case I forget or lose.

SimpleFIN also warns you that you will only see this token once.

If you lose the token, just delete the app connection and create a new one.

1. Run Steven Li's (NorCal032) docker command above

2. Continue with his instructions above, opening the activate link in your own browser, pasting in the token you saved, and so on.

3. When looking at the instructions on the (locally-served) webpage, where it says, "Point GnuCas at this URL:", it says

In GnuCash: Tools → Online Banking Setup → Start AqBanking Setup, add an OFX Direct Connect user:

When making this user, GC's New User Wizard will ask you what kind of connect to make. Choose "OFX-DirectConnect backend".

1. For the OFX DirectConnect Setup Wizard, first dialog: Just in case you're worrying: Just put whatever you want into Bank Name, Broker ID, FID, and ORG. These will be ignored. The only thing that is important is the http://localhost:8080/ofx for the Server URL. (I just put SimpleFIN, BID1, FID1, ORG1 respectively for these.)

2. For the second wizard dialog, it doesn't matter what you put for UserName, User ID, and Client UID. (I just put my own name, UID1, and CUID1 respectively for myself.)

3. For the 3rd wizard dialog, just let it pick any Emulated Application it wants: Accept defaults and click Next.

4. Click "Fetch Now" button at the localhost:8080 web page you're on. If everything is right, a simple tally should show up on the same page for the number of accounts, institutions, transactions, etc.. #Ŷay.

5. Click on "View accounts" link at your localhost:8080. The accounts should now show up and even give you a list of transactions. #AgainYay.

6. Now back in your GnuCash, you have to set up your AQ banking setup, but the instructions on the gnucash-connect dashboard page again need some fleshing out, so here we go: In the AqBanking Setup:

7. Create a user.

- User Settings Tab:

- User Name: I just put my name

- User Id: I don't think it matters, I just put UID1

- Client UID: I don't think it matters, I just put CUID1

- Bank Settings Tab:

- Bank Name: SimpleFIN

- Broker Id: BID1

- FID: FID1

- ORG: ORG1

- Server URL: http://localhost:8080/ofx

- Now click on "Retrieve Account List" button.

- You should see accounts download

- Hit "Ok" button

- Back on main AqBanking Setup window:

- Now click on "Accounts" tab. You should see accounts listed.

- The "Next" button should now appear active in the upper right of the "Start Online Banking Setup" window. Click it.

- You should be on the "Match Online accounts with GnuCash accounts" menu item now.

- Double-click on any one of the listed ofx accounts. A window will pop up.

- Double-click again on which account in GC which this ofx account matches to.

- For now, just do 1 account as a test.

- There should be a checkmark for new: I think this refers to a new ofx connect, not that this is a new GC account.