...
Analyzes American Express credit card statements to provide spending insights, subscription detection, fraud alerts, and vendor unmasking from CSV exports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AmexAnalysis-MCP Show me recurring payments from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Point it at an Amex activity CSV. It unmasks processor descriptors, splits charges from credits and payments, and answers follow-up questions from the statement already in memory.
There is no HTTP server and no database. The file you name is the only data it sees.
Statement line | Vendor | Processor |
| Grubhub | PayPal |
| Blue Bottle | Square |
| Substack | Stripe |
| Corner Cafe | Toast |
Vendor unmasking. PayPal, Square, Stripe, Toast, Venmo, Cash App, Zelle, Clover, Shop Pay, Klarna, Afterpay, Apple Pay, and Google Pay. Specific merchant maps only — COFFEE does not become “Local Coffee Shop.”
Honest totals. Card payments (ONLINE PAYMENT THANK YOU, autopay, and similar) are never counted as spend. Credits stay credits. Sign convention is detected from the file, because Amex exports come both ways.
One load per session. Call load_statement once. Later tools omit csvPath and reuse the parsed file until it changes on disk.
Subscriptions. Known services plus recurring amount and interval. “Unused” is measured from the statement end date, not today’s clock.
Two surfaces. Ask Claude, or run analyze / unmask in a terminal. Excel, CSV, and JSON export from both.
Not in scope. It does not log into American Express, fetch receipts, read Chase or Citi files, or train a model on your data.
Related MCP server: Excel Analytics MCP Server
Requires Node.js 18.18 or newer and an Amex activity CSV with Date, Description, and Amount.
git clone https://github.com/ogprotege/amex-anaylsis-mcp.git
cd amex-anaylsis-mcp
npm install
npm test
npm run buildnpm test and npm run test-unmasking generate their own sample CSV. You do not need to put a personal statement in the repo.
Add the server, then restart Claude Desktop.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"amex-analysis": {
"command": "node",
"args": ["/absolute/path/to/dist/amex-mcp-server.js"]
}
}
}Then:
Load ~/Downloads/activity.csv
What are my subscriptions this period?
Unmask the PayPal and Square charges
Search Uber over $20After load_statement, later tools can omit csvPath. You can also read amex://statement/summary or use the review_subscriptions prompt.
{
"mcpServers": {
"amex-analysis-enhanced": {
"command": "node",
"args": ["/absolute/path/to/dist/amex-mcp-server-enhanced.js"]
}
}
}Both can be registered at once. Dev without building: npm run dev (standard) or npm run dev:enhanced. Details: ENHANCED_SERVER_GUIDE.md.
npx tsx src/cli.ts --help
npx tsx src/cli.ts unmask "PAYPAL *GRUBHUB"
npx tsx src/cli.ts analyze data/amex.csv
npx tsx src/cli.ts analyze data/amex.csv --format excel --out output/report.xlsx
npx tsx src/cli.ts serve --mode enhancedAfter npm run build, the same commands are node dist/src/cli.js .... If the package is linked, amex-analysis is the binary name.
$ npx tsx src/cli.ts unmask "PAYPAL *GRUBHUB"
PAYPAL *GRUBHUB
Vendor: Grubhub
Processor: PayPal
Confidence: 90%
Needs review: noThe analyze sample is the project fixture CSV, not a live account. Payments are listed on their own line. They are not spend.
flowchart LR
CSV[Amex activity CSV] --> Load[load_statement]
Load --> Cache[Session cache]
Cache --> Tools[Tools]
Cache --> Res[amex://statement/*]
Cache --> Prompts[Prompts]The cache keys on path and mtime. Edit the CSV and the next tool call reloads it. Paths are resolved from the server’s working directory, not from Claude’s UI.
Mode | Start | Catalog |
Basic |
|
|
Standard |
| Basic, plus unmask, search, trends, duplicates, period compare |
Enhanced |
| Full catalog |
Standard mode (the default) is enough for everyday review.
Tool | Does |
| Read the CSV once |
| Summary, JSON, Excel, or CSV. Optional date and min-amount filters |
| Recurring services and monthly equivalent |
| One merchant, including unmasked processor charges |
| Unusual amounts and same-day duplicates |
| Category totals |
| Processor-masked descriptors in the loaded file |
| Text and amount search |
| Spend over the statement window |
| Same vendor, same day, same amount |
| Two date ranges in one file |
| Write Excel / CSV / JSON |
Enhanced mode adds tax buckets, accounting export, budget alerts, unused-subscription checks, and the rest of the catalog. Those are analysis helpers, not tax advice. See ENHANCED_SERVER_GUIDE.md.
Resources after a load: amex://statement/summary, subscriptions, categories, anomalies, unmasked.
Prompts: review_subscriptions, find_waste, unmask_processors, monthly_review.
Official Amex activity exports work, including a title row before the header.
Required | Optional, used when present |
| Extended details, statement description, city/state, category, card member |
Dates parse as M/D/YYYY or YYYY-MM-DD in UTC. Account-number columns are ignored.
If Claude says the file was not found, the path is wrong relative to the MCP server’s cwd.
import { AmexSpendingAnalyzer } from './amex-mcp-server.js';
const analyzer = new AmexSpendingAnalyzer();
await analyzer.parseAmexCsv('data/amex.csv');
const results = analyzer.analyze();results includes vendors, charge / credit / payment totals, subscriptions, categories, and anomalies.
npm test # parser, unmasker, analyzer, session, CLI, catalog
npm run test-unmasking
npm run build
npm run demo # writes a sample CSV and an Excel fileStatements are read from the path you pass. Nothing is uploaded. Nothing is stored after the process exits, other than files you explicitly export.
MIT. See LICENSE.
Analyze Amex credit card spending from CSV file
| Name | Required | Description | Default |
|---|---|---|---|
| csvPath | Yes | Path to Amex CSV file | |
| outputPath | No | Output file path (optional) | |
| outputFormat | No | Output format for results | summary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It states that the tool analyzes spending from a CSV, but does not mention whether it writes output files, overwrites existing files, returns data in-memory, or has any side effects. The optional outputPath parameter hints at file output, but the description fails to clarify behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the tool's purpose. It contains no redundant information or fluff, making it appropriately concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity (one required parameter, two optional, no nested objects) and the well-documented schema, the description is adequate. However, the absence of an output schema means it could add more detail about what the analysis result looks like or how the output is delivered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters, including the enum for outputFormat and its default value. The description adds no additional parameter-level meaning beyond restating the overall purpose, so it does not exceed what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes Amex credit card spending from a CSV file, identifying the specific resource (Amex spending), action (analyze), and input source (CSV). It does not explicitly distinguish itself from sibling tools like spending_by_category or analyze_vendor, but the 'Amex CSV' qualifier provides some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention alternatives such as spending_by_category, find_anomalies, or analyze_vendor, nor does it give any exclusions or prerequisites. Usage context is only implied by the tool's name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed analysis of a specific vendor
| Name | Required | Description | Default |
|---|---|---|---|
| csvPath | Yes | Path to Amex CSV file | |
| vendorName | Yes | Name of vendor to analyze |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey whether the tool performs reads, writes, or other side effects. 'Get detailed analysis' implies a read operation but does not explicitly state what happens, what data is accessed, or what the output contains. This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, front-loading the action. It is appropriately sized for a simple tool, though it lacks detail that would be useful in the sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotation support, the description does not explain what 'detailed analysis' returns or what constitutes a successful invocation. The agent cannot infer what to expect from the tool's response, making it incomplete for a tool without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with clear descriptions for csvPath and vendorName. The tool description adds no additional parameter information, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes a specific vendor, using the verb 'get' and resource 'specific vendor'. However, it does not distinguish from sibling tools like analyze_amex_spending or spending_by_category, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided for when to use this tool versus alternatives. There is no mention of exclusions or context that would help the agent select it over siblings like find_subscriptions or find_anomalies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export comprehensive spending analysis
| Name | Required | Description | Default |
|---|---|---|---|
| format | Yes | Export format | |
| csvPath | Yes | Path to Amex CSV file | |
| outputPath | Yes | Output file path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It only says 'export,' which implies file creation, but does not mention overwrite behavior, return values, or whether it uses existing analysis results or reads fresh data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with no redundant words. While it is brief, the structure is efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and only a one-line description, the tool leaves many questions unanswered about the export process, file formats, and its relationship to sibling tools. It is not complete enough for an agent to understand the full pipeline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (csvPath, format, outputPath) having descriptions in the schema. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb 'export' with a resource 'comprehensive spending analysis,' which is distinct from the sibling analysis tools. However, 'comprehensive' is vague and does not specify what the analysis entails or what the output contains, leaving room for ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool relative to alternatives, prerequisites, or whether it should follow another analysis tool. Sibling tools such as analyze_amex_spending or find_subscriptions suggest a workflow, but the description does not connect to it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find spending anomalies and potential fraud
| Name | Required | Description | Default |
|---|---|---|---|
| csvPath | Yes | Path to Amex CSV file | |
| severityThreshold | No | Minimum severity to report | medium |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must communicate behavioral traits, but it only states the tool's purpose. It does not disclose what the tool returns, whether it is read-only, how severity thresholds affect output, or any side effects, offering minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It states the core function efficiently and meets the conciseness standard.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should explain what the agent can expect from the tool. It only gives a high-level goal with no mention of output format, severity behavior, or practical usage context, making it incomplete for an anomaly-detection tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both csvPath and severityThreshold. The tool description adds no parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Find') with a distinct resource ('spending anomalies and potential fraud'), which clearly separates it from siblings like find_subscriptions and analyze_amex_spending. However, 'potential fraud' is broad and not further qualified, so it stops short of a fully precise purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The sibling tools imply different purposes, but the description does not state conditions, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all subscriptions in Amex transactions
| Name | Required | Description | Default |
|---|---|---|---|
| csvPath | Yes | Path to Amex CSV file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It implies a read-only search but gives no details on what constitutes a subscription, how matches are determined, or what the output contains. The word 'find' suggests no side effects, but that is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler; it is concise and front-loaded. The brevity is appropriate given the simple structure, though it contributes to the transparency gap.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the core action, but it does not explain the return format or edge cases, nor how subscriptions are defined. Given no output schema and no annotations, the description leaves some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents csvPath with 'Path to Amex CSV file', and the description adds no extra meaning about parameter constraints or behavior. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds subscriptions within Amex transactions, using a specific verb and resource. The noun 'subscriptions' distinguishes it from sibling tools like find_anomalies or spending_by_category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings like find_anomalies or analyze_amex_spending, nor any exclusions or prerequisites. The context is implied solely by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze spending broken down by category
| Name | Required | Description | Default |
|---|---|---|---|
| csvPath | Yes | Path to Amex CSV file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only says 'Analyze spending broken down by category' without explaining what the output looks like, how categories are determined, whether any data is written or exported, or any other side effects. This leaves significant ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no waste. It front-loads the core action and scope. While extremely terse, it does earn its place by stating the primary purpose, though it could benefit from a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool takes a single parameter and has no output schema, but with no annotations, the description must carry more weight. It fails to disclose the return format, aggregation details, or how this tool differs from closely related siblings. The context is insufficient for an agent to reliably invoke the tool and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for csvPath ('Path to Amex CSV file'), and schema coverage is 100%. The description adds no extra parameter semantics beyond what the schema defines. Thus, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Analyze spending broken down by category' clearly identifies the verb (analyze), resource (spending), and the specific scope (broken down by category). This distinguishes it from sibling tools like 'analyze_vendor' (vendor breakdown) and 'find_anomalies' (anomaly detection). Though 'analyze' is generic, the category breakdown adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used when a category-level breakdown of spending is needed, but it does not explicitly state when to use it versus alternatives like 'analyze_amex_spending' or 'analyze_vendor'. There is no mention of when not to use it or which sibling tools are preferred for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0analyze_amex_spendinganalyze_vendorexport_analysisfind_anomaliesfind_subscriptionsspending_by_categoryScored across 6 tools
Each tool targets a distinct analytical aspect: overall spending, subscriptions, specific vendors, anomalies, category breakdown, and export. No meaningful overlap exists between them.
Five of six tools follow a clear verb_noun convention (analyze_*, find_*, export_*). The outlier, spending_by_category, uses a noun phrase but is still readable and not jarringly inconsistent.
Six tools is a well-scoped count for a specialized spending-analysis server. Each tool covers a distinct need without redundancy or bloat.
The surface covers the core analysis lifecycle: overall analysis, drill-downs (vendor, category), anomaly detection, and export. Minor gaps like time-period comparison or raw transaction listing could be added, but the current set supports typical workflows.
Turn bank statement PDFs, CSVs, XLSX and OFX into categorised transactions plus a summary.
Amazon Seller Central and Ads inside Claude or ChatGPT. Real fees from your own settlements.
The Ramp MCP server enables users to securely connect Ramp with AI assistants like ChatGPT and Claude to query financial data and take actions using natural language. It transforms Ramp's developer API into a SQL interface that LLMs can query, allowing admins to analyze spend trends, identify cost savings, and run complex SQL analyses on comprehensive datasets (transactions, purchase orders, vendors, users), while all users can manage cards, view transactions, request reimbursements, and get expense policy answers.
Turn bank statement PDFs into categorized, balance-checked transactions and reports.
