@expensebot/mcp-server-auth 0.4.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -0
- package/package.json +1 -1
- package/src/index.js +115 -0
package/README.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# @expensebot/mcp-server-auth
|
|
2
|
+
|
|
3
|
+
Authenticated MCP (Model Context Protocol) server for [ExpenseBot](https://www.expensebot.ai). Lets Claude Desktop, Cursor, Claude Code, Continue, Cline, Windsurf, and any MCP-compatible AI assistant search receipts, submit photos, scan Gmail, create reports, and analyze spending using your real ExpenseBot account.
|
|
4
|
+
|
|
5
|
+
**21 tools** across:
|
|
6
|
+
- **Search & analytics** — `search_expenses`, `get_spending_summary`, `get_deep_analytics`, `list_categories`, `list_tags`, `search_knowledge`
|
|
7
|
+
- **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`
|
|
8
|
+
- **Gmail** — `scan_gmail`, `process_gmail_receipts`
|
|
9
|
+
- **Reports** — `create_report`, `list_reports`, `get_report_details`, `share_report`
|
|
10
|
+
- **Compliance & tax** — `check_compliance`, `fix_compliance`, `check_tax_deductibility`
|
|
11
|
+
- **Onboarding** — `get_signup_link`
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
**Full step-by-step instructions for every supported client live at:**
|
|
16
|
+
|
|
17
|
+
→ **<https://www.expensebot.ai/mcp>**
|
|
18
|
+
|
|
19
|
+
### Quick start (Claude Desktop)
|
|
20
|
+
|
|
21
|
+
1. Sign in at [expensebot.ai](https://www.expensebot.ai) → Settings → AI Assistant Tokens → Generate
|
|
22
|
+
2. Copy the token (shown once)
|
|
23
|
+
3. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"mcpServers": {
|
|
28
|
+
"expensebot": {
|
|
29
|
+
"command": "npx",
|
|
30
|
+
"args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
4. Restart Claude Desktop
|
|
37
|
+
|
|
38
|
+
### Quick start (Claude Code CLI)
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth --token=YOUR_TOKEN_HERE
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Quick start (Cursor)
|
|
45
|
+
|
|
46
|
+
Edit `~/.cursor/mcp.json`:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"expensebot": {
|
|
52
|
+
"command": "npx",
|
|
53
|
+
"args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Then in Cursor: Settings → Tools & Integrations → confirm the green dot next to **expensebot**.
|
|
60
|
+
|
|
61
|
+
### Continue, Cline, Windsurf, custom clients
|
|
62
|
+
|
|
63
|
+
Same `npx -y @expensebot/mcp-server-auth --token=...` command in your client's MCP config.
|
|
64
|
+
|
|
65
|
+
## Token model
|
|
66
|
+
|
|
67
|
+
- **Personal Access Tokens (PAT)** scoped to your ExpenseBot account
|
|
68
|
+
- **Configurable expiry**, revokable instantly from Settings → AI Assistant Tokens
|
|
69
|
+
- **Max 5 active tokens per user** — generate one per device/AI client
|
|
70
|
+
- All actions audit-logged server-side
|
|
71
|
+
- Tokens stored as SHA-256 hashes; CASA Tier 2 certified
|
|
72
|
+
|
|
73
|
+
## Listed on
|
|
74
|
+
|
|
75
|
+
- **Official MCP Registry** — `io.github.TotesMagotes/mcp-server-auth`
|
|
76
|
+
- **awesome-mcp-servers** — Finance & Fintech section
|
|
77
|
+
- **Glama** — <https://glama.ai/mcp/servers/TotesMagotes/expensebot>
|
|
78
|
+
|
|
79
|
+
## Onboarding mode (no token)
|
|
80
|
+
|
|
81
|
+
Running without a token exposes 2 read-only tools that help new users sign up:
|
|
82
|
+
- `get_signup_link` — returns ExpenseBot signup URL
|
|
83
|
+
- `search_knowledge` — searches the public ExpenseBot knowledge base
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
npx @expensebot/mcp-server-auth
|
|
87
|
+
# (no --token argument)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Useful for AI agents evaluating ExpenseBot before a user has an account.
|
|
91
|
+
|
|
92
|
+
## Read-only docs server
|
|
93
|
+
|
|
94
|
+
For pure pre-sales discovery (no account, no token):
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npx @expensebot/mcp-server
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. Useful for AI agents answering "does ExpenseBot support X?" type questions.
|
|
101
|
+
|
|
102
|
+
## Source / issues / support
|
|
103
|
+
|
|
104
|
+
- Source: <https://github.com/TotesMagotes/expensebot/tree/master/mcp-server-auth>
|
|
105
|
+
- Issues: email `support@expensebot.ai`
|
|
106
|
+
- Roadmap (remote HTTPS MCP for ChatGPT + Claude.ai web): <https://www.expensebot.ai/mcp>
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@expensebot/mcp-server-auth",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"mcpName": "io.github.TotesMagotes/mcp-server-auth",
|
|
5
5
|
"description": "Authenticated MCP server for ExpenseBot — lets Claude Desktop, Cursor, and other AI assistants search your expenses, create reports, and analyze spending using your actual ExpenseBot data.",
|
|
6
6
|
"bin": {
|
package/src/index.js
CHANGED
|
@@ -437,6 +437,109 @@ const TOOLS = [
|
|
|
437
437
|
},
|
|
438
438
|
},
|
|
439
439
|
},
|
|
440
|
+
{
|
|
441
|
+
name: "add_mileage_entry",
|
|
442
|
+
description:
|
|
443
|
+
"Log a business mileage trip in ExpenseBot. Useful for realtors, " +
|
|
444
|
+
"consultants, contractors, and anyone who drives for work. Requires " +
|
|
445
|
+
"the user to have configured their mileage rate (cents/km or cents/mi) " +
|
|
446
|
+
"and unit (mi/km) in ExpenseBot Settings. The trip writes a row to " +
|
|
447
|
+
"their expense spreadsheet with the calculated dollar value.",
|
|
448
|
+
inputSchema: {
|
|
449
|
+
type: "object",
|
|
450
|
+
properties: {
|
|
451
|
+
distance: {
|
|
452
|
+
type: "number",
|
|
453
|
+
description: "Distance traveled in the user's configured unit (miles or km)",
|
|
454
|
+
},
|
|
455
|
+
purpose: {
|
|
456
|
+
type: "string",
|
|
457
|
+
description: "Business purpose / description of the trip (e.g., 'Client meeting at 1234 Main St')",
|
|
458
|
+
},
|
|
459
|
+
date: {
|
|
460
|
+
type: "string",
|
|
461
|
+
format: "date",
|
|
462
|
+
description: "Trip date (YYYY-MM-DD). Defaults to today.",
|
|
463
|
+
},
|
|
464
|
+
roundTrip: {
|
|
465
|
+
type: "boolean",
|
|
466
|
+
description: "If true, doubles the distance (return trip)",
|
|
467
|
+
default: false,
|
|
468
|
+
},
|
|
469
|
+
destination: {
|
|
470
|
+
type: "string",
|
|
471
|
+
description: "Destination address or location (optional)",
|
|
472
|
+
},
|
|
473
|
+
city: {
|
|
474
|
+
type: "string",
|
|
475
|
+
description: "City (optional)",
|
|
476
|
+
},
|
|
477
|
+
category: {
|
|
478
|
+
type: "string",
|
|
479
|
+
description: "Override the user's default mileage category (optional)",
|
|
480
|
+
},
|
|
481
|
+
tag: {
|
|
482
|
+
type: "string",
|
|
483
|
+
description: "Tag for client/project attribution (optional)",
|
|
484
|
+
},
|
|
485
|
+
notes: { type: "string" },
|
|
486
|
+
},
|
|
487
|
+
required: ["distance", "purpose"],
|
|
488
|
+
},
|
|
489
|
+
},
|
|
490
|
+
{
|
|
491
|
+
name: "add_income",
|
|
492
|
+
description:
|
|
493
|
+
"Log an income entry manually (cash, check, Stripe payout, etc.). " +
|
|
494
|
+
"Writes to the Income tab of the user's expense spreadsheet. Useful " +
|
|
495
|
+
"for income that isn't auto-detected from Gmail or Plaid.",
|
|
496
|
+
inputSchema: {
|
|
497
|
+
type: "object",
|
|
498
|
+
properties: {
|
|
499
|
+
amount: { type: "number", description: "Income amount (>0)" },
|
|
500
|
+
source: {
|
|
501
|
+
type: "string",
|
|
502
|
+
description: "Who paid you (client name, customer, etc.)",
|
|
503
|
+
},
|
|
504
|
+
paymentMethod: {
|
|
505
|
+
type: "string",
|
|
506
|
+
description: "How you got paid (e.g., 'Cash', 'Check', 'Stripe', 'Bank Transfer', 'Venmo')",
|
|
507
|
+
},
|
|
508
|
+
date: {
|
|
509
|
+
type: "string",
|
|
510
|
+
format: "date",
|
|
511
|
+
description: "Income date (YYYY-MM-DD). Defaults to today.",
|
|
512
|
+
},
|
|
513
|
+
currency: { type: "string", description: "Currency code (default: home currency)" },
|
|
514
|
+
description: { type: "string", description: "What the income was for" },
|
|
515
|
+
category: { type: "string", description: "Income category (optional)" },
|
|
516
|
+
reference: { type: "string", description: "Invoice or transaction reference" },
|
|
517
|
+
fees: { type: "number", description: "Processor/transfer fees deducted" },
|
|
518
|
+
taxCollected: { type: "number", description: "Sales tax/GST/HST collected" },
|
|
519
|
+
tag: { type: "string", description: "Tag for client/project attribution" },
|
|
520
|
+
notes: { type: "string" },
|
|
521
|
+
},
|
|
522
|
+
required: ["amount", "source", "paymentMethod"],
|
|
523
|
+
},
|
|
524
|
+
},
|
|
525
|
+
{
|
|
526
|
+
name: "list_categories",
|
|
527
|
+
description:
|
|
528
|
+
"List the user's configured expense categories and billing accounts. " +
|
|
529
|
+
"Use this BEFORE calling tools that need a category (add_cash_expense, " +
|
|
530
|
+
"add_mileage_entry, create_report) so you pass the user's actual " +
|
|
531
|
+
"category names, not guesses. Returns the live list from their spreadsheet.",
|
|
532
|
+
inputSchema: { type: "object", properties: {} },
|
|
533
|
+
},
|
|
534
|
+
{
|
|
535
|
+
name: "list_tags",
|
|
536
|
+
description:
|
|
537
|
+
"List the user's configured tags. Tags are used for client/project " +
|
|
538
|
+
"attribution (e.g., 'Client: Acme', 'Q1 Trip', 'Property: 123 Main'). " +
|
|
539
|
+
"Use this BEFORE calling tools that filter or assign tags so you pass " +
|
|
540
|
+
"valid tag names, not guesses.",
|
|
541
|
+
inputSchema: { type: "object", properties: {} },
|
|
542
|
+
},
|
|
440
543
|
];
|
|
441
544
|
|
|
442
545
|
// Tools available without authentication (onboarding mode)
|
|
@@ -595,6 +698,18 @@ async function handleTool(name, args) {
|
|
|
595
698
|
})
|
|
596
699
|
);
|
|
597
700
|
|
|
701
|
+
case "add_mileage_entry":
|
|
702
|
+
return formatResult(await client.execute("add_mileage_entry", args));
|
|
703
|
+
|
|
704
|
+
case "add_income":
|
|
705
|
+
return formatResult(await client.execute("add_income", args));
|
|
706
|
+
|
|
707
|
+
case "list_categories":
|
|
708
|
+
return formatResult(await client.execute("list_categories", {}));
|
|
709
|
+
|
|
710
|
+
case "list_tags":
|
|
711
|
+
return formatResult(await client.execute("list_tags", {}));
|
|
712
|
+
|
|
598
713
|
default:
|
|
599
714
|
return {
|
|
600
715
|
content: [{ type: "text", text: `Unknown tool: ${name}` }],
|