BeanHub MCP server
Commit Sep 20, 2026Allows an AI client to read and update hosted Beancount ledgers using OAuth authentication.
Also known as LaunchPlatform/beanhub-mcp, beanhub-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Sep 20, 2026
- License
- MIT
What is BeanHub MCP?
BeanHub allows an AI client to read and update hosted Beancount ledgers using OAuth authentication.
Summary generated from the project's README
About BeanHub MCP server
BeanHub provides a hosted MCP server that connects AI clients to Beancount ledgers stored on Git. This service is designed for users who want to interact with their financial records through AI applications using OAuth 2.0 authentication. Instead of using a CLI access token, the AI signs in via OAuth to access your data.
By default, all new connections operate in a read-only mode. Users can expand these capabilities by enabling updates within their account settings. Once enabled, the AI can use specific write tools to modify the ledger. The server supports various client configurations, including Cursor, Claude Code, and Gemini CLI, by providing specialized configuration files for each environment.
Available read tools include searching transactions, checking balances, and listing accounts or files. If write permissions are granted, the AI can also perform tasks like creating entries, updating entries, deleting entries, or renaming accounts. The server is hosted at a remote endpoint and does not allow the AI to change billing, connect banks, or delete entire books.
What you can do with it
- 1Analyze financial balancesAsk the AI to retrieve current account balances from your Beancount ledger.
- 2Search transaction historyRequest the AI to find specific past transactions within your hosted books.
- 3Manage account structuresHave the AI rename an existing account within your ledger.
Written from the project's README. Every use case is checked against a quote from it.
How to install BeanHub MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall BeanHub MCP in Claude Code
$ claude mcp add --transport http beanhub-mcp https://api.beanhub.io/mcpInstall BeanHub MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"beanhub-mcp": {
"url": "https://api.beanhub.io/mcp"
}
}
}Install BeanHub MCP in VS Code
.vscode/mcp.json
{
"servers": {
"beanhub-mcp": {
"type": "http",
"url": "https://api.beanhub.io/mcp"
}
}
}Install BeanHub MCP in VS Code CLI
$ code --add-mcp '{"name":"beanhub-mcp","type":"http","url":"https://api.beanhub.io/mcp"}'Install BeanHub MCP in Codex
$ codex mcp add beanhub-mcp --url https://api.beanhub.io/mcpInstall BeanHub MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.beanhub-mcp] url = "https://api.beanhub.io/mcp"
Install BeanHub MCP in Gemini CLI
$ gemini mcp add -s user --transport http beanhub-mcp https://api.beanhub.io/mcpInstall BeanHub MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"beanhub-mcp": {
"url": "https://api.beanhub.io/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelaunchplatform/beanhub-mcp is public and reachablegithub.com/launchplatform/beanhub-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-20github.com/launchplatform/beanhub-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubBeanHub MCP
Listing files for BeanHub's hosted MCP server. This repository is not the server source. The live endpoint is https://api.beanhub.io/mcp.
BeanHub is a hosted Beancount book on Git. An AI app signs in with OAuth, then can list accounts, search transactions, check balances, and update the ledger if you allow it. The app does not use a CLI access token. New connections start read-only.
Enable MCP on your account before you connect: https://app.beanhub.io/mcp/. Full steps: Connect an AI app with MCP.
Files
Each client looks for its own filename. They all point at the same URL.
| File | Used by |
|---|---|
server.json |
Official MCP Registry (io.beanhub/mcp) |
mcp.json |
Cursor plugins and Agent Plugins |
.mcp.json |
Claude Code plugins |
plugin.json |
Agent Plugins |
.cursor-plugin/plugin.json |
Cursor Marketplace |
.claude-plugin/plugin.json |
Claude Code plugins |
.claude-plugin/marketplace.json |
Claude Code marketplace catalog |
gemini-extension.json |
Gemini CLI gallery |
Do not paste https://app.beanhub.io/mcp/ into an AI app. That page is MCP settings, not the server.
Auth
The server uses OAuth 2.0 with dynamic client registration and token_endpoint_auth_method=none. Do not add a Bearer access token or a static client secret.
What the app can do
Read tools: list_books, list_accounts, search_transactions, get_balances, list_entries, get_entry, list_files, get_file, list_forms, list_commits.
Write tools (only if you turn on updates): create_entries, update_entry, delete_entry, rename_account, submit_form, update_files.
The app cannot mint access tokens, change billing, connect a bank, dump Connect or Inbox data, make a book public, or delete a book.
Public source
The public copy is https://github.com/LaunchPlatform/beanhub-mcp. Cursor, Claude Code, Gemini CLI, and the official registry repository.source field use that GitHub repo.
To pull Amendable updates and push GitHub:
cd beanhub-mcp
git fetch origin
git merge origin/master
git push github master
For Gemini CLI gallery, add the GitHub topic gemini-cli-extension.
Official MCP Registry
This repo publishes metadata only for the hosted server https://api.beanhub.io/mcp. The registry name is io.beanhub/mcp. That namespace needs HTTP or DNS proof on beanhub.io, not GitHub OIDC. Docs: remote servers, authentication, GitHub Actions.
Do not run mcp-publisher init. It would overwrite server.json.
devenv
direnv allow # or: devenv shell
mcp-validate
mcp-gen-auth # encrypts MCP_PRIVATE_KEY into secrets.sops.yaml + gitignored mcp-registry-auth
The publisher key is stored in secrets.sops.yaml, encrypted with SOPS using PGP fingerprint A57616E62A499B512EDA662E0FC8D7008588874B. Edit later with sops secrets.sops.yaml. Commit the encrypted file; do not commit key.pem.
The public proof is served from the Hugo site as static/.well-known/mcp-registry-auth. Deploy beanhub.io so https://beanhub.io/.well-known/mcp-registry-auth returns that one line. DNS alternative: TXT on the apex beanhub.io. Then:
mcp-publish
mcp-publish reads MCP_PRIVATE_KEY (64 hex chars), decrypts ./secrets.sops.yaml, or falls back to ./key.pem. Default auth method is HTTP. For DNS: MCP_AUTH_METHOD=dns mcp-publish.
Without devenv:
./scripts/validate-mcp.sh
./scripts/gen-mcp-registry-auth.sh
./scripts/publish-mcp.sh
GitHub Actions
CI runs ./scripts/validate-mcp.sh on pulls and pushes to master.
Publish to MCP Registry runs on v* tags and on workflow_dispatch. Create a GitHub Environment named mcp-registry-publish, store MCP_PRIVATE_KEY as an environment secret (not a repo secret), and restrict the environment to master and tags. Then:
git tag v1.0.0
git push github v1.0.0
A tag v1.0.0 publishes version 1.0.0 (the committed server.json is not rewritten). Versions are immutable. Bump the tag for later metadata-only updates.
Confirm:
curl -sS "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.beanhub/mcp"
Links
- App: https://app.beanhub.io
- Docs: https://docs.beanhub.io/guides/mcp/
- Privacy: https://beanhub.io/privacy-policy
- Terms: https://beanhub.io/terms-of-service
- Support: support@beanhub.io
BeanHub MCP questions
How do I add BeanHub MCP to Claude Code?
Run claude mcp add --transport http beanhub-mcp https://api.beanhub.io/mcp in your terminal. Add --scope user to make it available in every project.
How do I add BeanHub MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the AI app authenticate with BeanHub?
The app uses OAuth 2.0 for authentication instead of a CLI access token.
What are the limitations of the AI app's access?
The app cannot change billing, connect a bank, change privacy settings, or delete a book.