Monexa

io.github.emilijan-koteskiPublished by GitHub account emilijan-koteskiv2.0.0Updated Oct 25, 2026

Track expenses and income, recurring payments and spending trends in Monexa from any AI assistant.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowFinance

Overview

AI-generated overview

Monexa is a remote MCP server that lets an AI assistant read and manage a user's expense and income records, categories, payment methods, recurring payments and

What you can do
Read and manage expense and income records, categories and payment methods through the Monexa API. Work with recurring expenses and spending trend reports. Read and adjust account settings. Tools are grouped by the backend routes they cover, with read-only and write tools distinguished by annotations.
When to use it
Useful when you track personal finances in Monexa and want an assistant to look up spending, log or edit records, and review recurring payments and trends without switching apps.
Requirements
A remote endpoint at mcp.monexa.world over Streamable HTTP. Authentication is OAuth and required: a Monexa OAuth access token from the sign-in flow, or a personal access token created in the web app under Settings, Connected apps, sent as a bearer token. Self-hosting needs Node 22, a running Monexa backend with OAuth enabled, and the documented environment variables including the OAuth client ID and secret.
Before you install
The server acts on real financial records: some tools can create, change or delete expenses, income, categories, payment methods and recurring payments, so review write actions before approving them. Access is limited by the monexa.read and monexa.write scopes. Self-hosters must supply an OAuth client secret of at least 32 characters and keep it matched with the backend. Tokens are exchanged with the Monexa backend, which sees the requests.

Installation

In SourceWeft

  1. Open Monexa in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.emilijan-koteski%2Fmonexa/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "monexa": {
      "type": "http",
      "url": "https://mcp.monexa.world/mcp"
    }
  }
}

README

Monexa MCP server

Remote Model Context Protocol server for Monexa, served over Streamable HTTP at https://mcp.monexa.world/mcp. It lets AI assistants read and manage a user's records, categories, payment methods, recurring expenses, trend reports and settings.

This README is for developers and self-hosters. To connect an assistant, see the user guide. The tools are listed in TOOLS.md. Released under the MIT license.

How it works

  1. An AI app connects with a Monexa OAuth access token (mnx_at_…, obtained through the OAuth flow the backend serves) or a personal access token (mnx_pat_…) in Authorization: Bearer.
  2. The server exchanges the bearer at the backend (RFC 8693, POST /oauth/token, authenticated as the MCP client) for a short-lived delegated JWT. Successful exchanges are cached in memory, keyed by a hash of the token, for at most 4 minutes, and tokens the backend rejects are answered from memory for 30 seconds.
  3. Each tool call runs with that JWT against the Monexa REST API (MONEXA_API_URL). The backend only lets delegated tokens reach an allowlist of routes (internal/middlewares/delegated_access.go) and checks the monexa.read / monexa.write scope.
  4. The server advertises the backend as its authorization server through protected resource metadata, so OAuth clients discover where to sign in. It mirrors the backend's metadata document, fetched at startup.
  5. The server is stateless and keeps no user data. Every request builds its own MCP server instance.

Environment

Set these on the service. The server refuses to start with a clear message when one is missing or malformed.

VariableRequiredMust match backendDescription
PORTNoListen port, default 8080.
MCP_PUBLIC_URLYesMCP_RESOURCE_URL (this value plus /mcp)Public origin of this server, for example https://mcp.monexa.world. No path. http is only accepted for localhost, 127.0.0.1 and [::1].
MONEXA_OAUTH_ISSUERYesOAUTH_ISSUER_URLPublic OAuth issuer, for example https://api.monexa.world. A bare origin without trailing slash; it is compared verbatim with the issuer in the backend's metadata.
MONEXA_API_URLYesBackend base URL reachable from this service, for example http://backend:8080. Not necessarily public.
MCP_CLIENT_IDYesMCP_CLIENT_IDThe OAuth client the backend recognizes for token exchange.
MCP_CLIENT_SECRETYesMCP_CLIENT_SECRETAt least 32 characters. Generate it with openssl rand -hex 32.
ALLOWED_HOSTSIn productionComma-separated hostnames accepted in the Host header; must include the MCP_PUBLIC_URL host. Defaults to localhost,127.0.0.1 outside production (NODE_ENV=production makes it required).
OPENAI_APPS_CHALLENGE_TOKENNoServed as plain text at /.well-known/openai-apps-challenge for OpenAI domain verification; the route is absent when unset.

The backend side of the same setup is OAUTH_ISSUER_URL, MCP_RESOURCE_URL, MCP_CLIENT_ID and MCP_CLIENT_SECRET, optionally OAUTH_ACCESS_TOKEN_TTL (default 1h) and OAUTH_REFRESH_TOKEN_TTL (default 2160h). The backend needs all four or none, and serves no OAuth routes without them. Deployment details are in docs/DEPLOYMENT.md.

Routes

RouteDescription
POST /mcpThe MCP endpoint. A bearer token is required.
GET /.well-known/oauth-protected-resource/mcpProtected resource metadata.
GET /.well-known/oauth-authorization-serverMirror of the backend's authorization server metadata.
GET /.well-known/openai-apps-challengeOpenAI domain verification token, when configured.
GET /healthz200 {"status":"ok","version":…} once the backend's metadata has loaded, 503 before. It is not subject to host validation, so container probes on 127.0.0.1 work.
GET /icon.svg, GET /icon.pngThe Monexa icon advertised in serverInfo.icons.

Until the backend's metadata has loaded, every route except /healthz answers 503 with Retry-After. At startup the server fetches ${MONEXA_API_URL}/.well-known/oauth-authorization-server up to 30 times, 2 seconds apart, and exits with code 1 if it never succeeds or if the issuer differs from MONEXA_OAUTH_ISSUER. A backend outage or a rejected client secret reaches clients as 503, never 401, so they do not fall into a re-authentication loop.

Local development

Requires Node 22 and a running backend with OAuth enabled. Start the backend with

bash
OAUTH_ISSUER_URL=http://localhost:9000MCP_RESOURCE_URL=http://localhost:3001/mcpMCP_CLIENT_ID=monexa-mcpMCP_CLIENT_SECRET=<at least 32 characters>

in its environment, then run the MCP server with the same client credentials. npm run dev loads mcp-server/.env when it exists (git-ignored), so put them there:

bash
PORT=3001MCP_PUBLIC_URL=http://localhost:3001MONEXA_OAUTH_ISSUER=http://localhost:9000MONEXA_API_URL=http://localhost:9000MCP_CLIENT_ID=monexa-mcpMCP_CLIENT_SECRET=<same secret as the backend>
bash
cd mcp-servernpm installnpm run dev

Point the MCP Inspector (npx @modelcontextprotocol/inspector) at http://localhost:3001/mcp and sign in through OAuth, or paste a personal access token created in the web app under Settings, Connected apps.

Scripts

ScriptWhat it does
npm run devRuns src/index.ts with tsx watch.
npm run buildCompiles src to dist/ with tsc -p tsconfig.build.json.
npm startRuns the compiled server, node dist/index.js.
npm run typechecktsc --noEmit over src, scripts and test.
npm run checkThe drift guard, described below.
npm run docsRegenerates TOOLS.md from the tool registry.
npm testRuns the vitest suite in test/. Tests are local-only by project policy: they are never committed and CI does not run them.

The drift guard

npm run check exits 1 with readable messages unless all of these hold:

  • Every route in ../docs/api-routes.json (the backend's route inventory, written by go run ./cmd/routes -write) is covered by exactly one tool's covers list or listed in src/tools/excluded.ts with a reason, and every covers or excluded entry exists in the inventory.
  • Every route a tool covers is marked "delegated": true in the inventory, which means the backend allowlist in internal/middlewares/delegated_access.go lets connected apps call it.
  • Tool names are unique snake_case of at most 64 characters, and each tool has a title and the four annotation hints, with openWorldHint: false.
  • Tools with readOnlyHint: true cover only GET routes.
  • TOOLS.md equals what npm run docs generates.
  • server.json has the same version as package.json and a description of at most 100 characters.

When the backend gains a route or its delegated allowlist changes, go run ./cmd/routes -check fails first. Run it with -write, then add a tool that covers the route or an entry in excluded.ts, run npm run docs, and commit the results together.

Tools

22 tools cover 24 of the backend's 65 API routes; the other 41 are intentionally excluded, such as sign-in, session and account-security routes, OAuth endpoints, legal documents, data export and trend report editing (see src/tools/excluded.ts and the end of TOOLS.md). Tool names are snake_case, input names are camelCase (for example includeDetails), and inputs are validated with zod before any API call. Every tool declares title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint: false, and returns both structuredContent and a JSON text block.

Operations

  • Logging. One JSON line per /mcp request with the HTTP and JSON-RPC method, tool name, status, duration in milliseconds and the OAuth client ID. Tokens and tool arguments are never logged.
  • Shutdown. On SIGTERM or SIGINT the server stops accepting connections and lets in-flight requests finish. It exits 0 when they are done and forces exit 1 after 8 seconds.
  • Container. The Dockerfile builds a node:22-alpine image that runs as a non-root user and probes /healthz; the start period allows for the metadata retries.

Versioning and releases

The version in package.json follows SemVer; server.json must carry the same version, and npm run check enforces it.

  • Major: a tool is removed or renamed, or a tool's schema changes incompatibly.
  • Minor: a new tool or a new optional parameter.
  • Patch: fixes with no schema change.

Record changes under ## [Unreleased] in CHANGELOG.md (Keep a Changelog) and move them under the new version heading when releasing. Set a new tool's since to the version that introduces it.

To release, bump package.json, server.json and the changelog, merge to master, then push the tag mcp-vX.Y.Z (for example git tag mcp-v2.0.0 && git push origin mcp-v2.0.0). CI pushes the image ghcr.io/emilijan-koteski/monexa-mcp:vX.Y.Z and publishes server.json to the official MCP Registry as io.github.emilijan-koteski/monexa. Merging to master deploys the sha-<short> image to production independently of tags.

Support

Questions and bug reports: [email protected] or an issue on GitHub.

Source: mcp-server/README.md at commit 96d871a

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v2.0.0LatestOct 18, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts