BeanHub 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