Skip to main content
Glama
coolksrini

finpilot-mcp

by coolksrini
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

FinPilot MCP Server

AI Financial Co-Pilot for Claude Desktop and VS Code

MCP server providing financial analysis capabilities through the Model Context Protocol. Requests flow through the FinPilot Auth Service, which validates credentials and routes to the private orchestrator.

Features

  • Native integration with Claude Desktop and VS Code

  • Zero-config guest mode — stateless calculation tools work without an account

  • Authenticated mode — full personal finance tools (credit reports, portfolio, LAMF)

  • Cloud-powered analysis (no local computation required)

Related MCP server: trading-skills

Claude Desktop Setup

Edit Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Zero-config (guest mode — stateless tools only)

No account or API key needed. Stateless calculation tools (loan optimizer, APR calculator, etc.) work out of the box. Personal finance tools (credit report analysis, portfolio) require sign-in.

{
  "mcpServers": {
    "finpilot": {
      "command": "uv",
      "args": ["run", "finpilot-mcp"]
    }
  }
}

Authenticated (full access)

Generate an fp_ API key from myfinpilot.io → Settings → API Tokens, then add it here:

{
  "mcpServers": {
    "finpilot": {
      "command": "uv",
      "args": ["run", "finpilot-mcp"],
      "env": {
        "FINPILOT_GATEWAY_URL": "https://<auth-service>.run.app",
        "FINPILOT_API_KEY": "fp_your_token_here"
      }
    }
  }
}

Restart Claude Desktop after editing.

Environment Variables

Variable

Default

Description

FINPILOT_GATEWAY_URL

http://localhost:8080

Auth Service URL

FINPILOT_API_KEY

(none)

API key (fp_...). Omit for guest mode.

Command Line Usage

# Guest mode (zero-config)
uv run finpilot-mcp

# Authenticated mode
FINPILOT_GATEWAY_URL=https://<auth-service>.run.app \
FINPILOT_API_KEY=fp_your_token_here \
uv run finpilot-mcp

# HTTP mode (for local testing)
uv run finpilot-mcp --mode http --port 8002

CLI Options:

  • --mode — Transport mode: stdio (default) or http

  • --host — HTTP server host (default: 0.0.0.0)

  • --port — HTTP server port (default: 8002)

  • --reload — Enable auto-reload for development

Available Tools

Credit Analysis

  • analyze_credit_report — Analyze CIBIL/Experian/Equifax reports

  • get_credit_health — Credit health summary

Portfolio Analysis

  • analyze_portfolio — Analyze CAS statements or portfolio data

Loan Optimization

  • optimize_loans — LAMF and refinancing recommendations

Financial Planning

  • create_financial_plan — Goal-based financial planning

Architecture

┌─────────────────────────────────────┐
│  Claude Desktop / VS Code           │
└────────────┬────────────────────────┘
             │ MCP Protocol (STDIO)
             ▼
┌─────────────────────────────────────┐
│  finpilot-mcp (This Package)        │
│  - Lightweight MCP wrapper          │
│  - Optional FINPILOT_API_KEY auth   │
│  - No business logic                │
└────────────┬────────────────────────┘
             │ HTTPS + optional Bearer token
             ▼
┌─────────────────────────────────────┐
│  Auth Service (Public entry point)  │
│  - Token validation / guest assign  │
│  - In-process rate limiting         │
│  - Injects X-User-* headers         │
└────────────┬────────────────────────┘
             │ SA identity token (private)
             ▼
┌─────────────────────────────────────┐
│  Orchestrator (Private Cloud Run)   │
│  - Multi-agent ADK orchestration    │
│  - Business logic & algorithms      │
└─────────────────────────────────────┘

Development

# Install dependencies
cd backend/finpilot-mcp
uv sync

# Run in HTTP mode for local testing
FINPILOT_GATEWAY_URL=http://localhost:8080 \
uv run finpilot-mcp --mode http --port 8002

# Run tests
uv run pytest

Security

  • All API communication over HTTPS

  • API keys via environment variables only

  • No sensitive data stored locally

  • Secrets never in CLI arguments or code

License

MIT License

Available Tools

5 tools
analyze_credit_reportB

Analyze credit report from CIBIL, Experian, or Equifax.

ParametersJSON Schema
NameRequiredDescriptionDefault
dobNoDate of birth in DDMMYYYY format (e.g. "15081985") — used for password inference. CIBIL partner portals and Equifax use DOB directly as the password.
nameNoFirst name — used to auto-infer the password when not provided. CIBIL (mycibil.com): first 4 letters lowercase + birth year. Experian: first 4 letters uppercase + last 4 digits of mobile.
bureauNoCredit bureau name (cibil, experian, equifax) — auto-detected if not provided
mobileNo10-digit mobile number — last 4 digits used for Experian / CIBIL app format.
passwordNoPDF password if the file is password-protected.
file_pathYesPath or URL to the credit report PDF. Local path: /Users/name/Downloads/cibil_report.pdf Cloud URL: https://drive.google.com/... or https://1drv.ms/... (must be shared with "anyone with link can view")

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states that the tool analyzes a report; it omits critical behaviors like password inference, bureau auto-detection, file format handling, or error conditions. The schema parameter descriptions hint at these details, but the main description fails to surface them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no waste. However, it is extremely terse, potentially sacrificing clarity for brevity. While it is well-structured and front-loaded, the lack of context prevents a perfect score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, password inference, multiple bureaus, output schema exists), the one-sentence description is insufficient. It does not explain auto-detection, password handling, or supported file sources, leaving the agent with limited guidance beyond the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter having a descriptive comment. The main description adds no parameter-specific information. Baseline 3 is appropriate since the schema already provides sufficient semantic context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Analyze'), the resource ('credit report'), and specifies the three supported bureaus (CIBIL, Experian, Equifax). This distinguishes it effectively from sibling tools like get_credit_health or analyze_portfolio, which target different financial functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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, nor does it mention prerequisites, exclusions, or complementary tools. The sibling tools exist but are not referenced for differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_portfolioB

Analyze investment portfolio from a CAS PDF or direct data.

ParametersJSON Schema
NameRequiredDescriptionDefault
dobNoDate of birth in DDMMYYYY format — used alongside PAN to infer the password.
panNoPAN number — used to auto-infer the password if not provided (CAMS/NSDL/CDSL CAS PDFs are often protected with DOB in DDMMYYYY format).
passwordNoPDF password if the file is password-protected.
file_pathNoPath or URL to the CAS PDF (NSDL/CDSL/CAMS consolidated statement). Local path: /Users/name/Downloads/cas_statement.pdf Cloud URL: https://drive.google.com/... or https://1drv.ms/... (must be shared with "anyone with link can view")
portfolio_dataNoDirect portfolio data as a dict (alternative to PDF)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It only states 'analyze' without disclosing behavior (e.g., read-only, side effects, authentication needs), return format, or processing details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, zero waste. Perfectly concise for the information it conveys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with five parameters and an output schema, the description is too brief. It lacks context on output, workflow, or prerequisites, making it insufficient for an agent to fully understand invocations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The tool description adds minimal context (PDF vs direct data) but does not deepen understanding beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze investment portfolio from a CAS PDF or direct data.' It specifies the verb (analyze), resource (investment portfolio), and source options, distinguishing it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives or when to choose PDF vs direct data. Siblings are tangentially related (credit health, loans) but no explicit differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_financial_planB

Create comprehensive financial plan based on goals and current situation.

ParametersJSON Schema
NameRequiredDescriptionDefault
goalsYesList of financial goals (retirement, house, education, etc.) Each goal: {name, target_amount, target_date, priority}
user_idNoUser ID
current_situationYesCurrent financial status {income, expenses, assets, liabilities, risk_profile}

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It only states it creates a plan, but does not discuss side effects, required permissions, or whether it modifies existing data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It could benefit from additional structure to improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of sibling tools and an output schema (not described), the description lacks context about what the output contains, prerequisites, and when to use this tool over alternatives like analyze_portfolio.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains the parameters. The description adds no additional meaning beyond 'based on goals and current situation', which is redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (create) and the resource (comprehensive financial plan) and identifies the inputs (goals and current situation). It differentiates from sibling tools like analyze_portfolio or get_credit_health, which are analysis-focused.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (when you want to create a plan) but does not provide explicit guidance on when to use this tool over alternatives, nor does it mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_credit_healthC

Get current credit health summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
user_idNoUser ID (optional - uses authenticated user if not provided)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It only says 'get', implying read-only, but omits details like whether the summary is cached, real-time, or what data it includes. 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no fluff. Efficient communication, but could be slightly more informative without adding length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one optional parameter and an output schema (not shown), the description is minimally complete. However, it lacks context on the summary content or structure, which would help the agent understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the parameter description in the schema explains optionality. The description adds no further semantics, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and resource 'current credit health summary'. It is specific enough to distinguish from sibling tools like analyze_credit_report which implies more detailed analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 vs alternatives such as analyze_credit_report. The agent must infer that this is for a quick summary without explicit instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

optimize_loansC

Get loan optimization recommendations.

ParametersJSON Schema
NameRequiredDescriptionDefault
loansNoList of loans with details (outstanding, apr, emi, tenure)
user_idNoUser ID (uses authenticated user's loans if not provided)
portfolio_dataNoPortfolio holdings from analyze_portfolio result (required for LAMF collateral evaluation — pass the full result from a prior analyze_portfolio call)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. The description only states it 'gets recommendations' without mentioning whether it is read-only, requires authentication, has side effects, or what data it consumes. The output schema exists but is not referenced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise, but it fails to convey essential information. While efficient in length, it does not earn its place due to vagueness; it could be expanded to provide clarity without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, optional dependencies, output schema), the description is incomplete. It does not explain what optimization entails, how inputs relate, or what outputs to expect. The description lacks sufficient context for an agent to confidently invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the parameter descriptions in the schema are detailed (e.g., loans expects specific fields, portfolio_data references analyze_portfolio). The tool description adds no additional meaning, so the baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get loan optimization recommendations' uses a verb+noun, but 'optimization recommendations' is vague and does not specify the nature of the recommendations (e.g., repayment strategies, consolidation). It does not distinguish from sibling tools like analyze_portfolio or create_financial_plan, which could also involve recommendations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives such as analyze_portfolio or get_credit_health, nor does it mention prerequisites or scenarios where it is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedanalyze_credit_report
    • First observedanalyze_portfolio
    • First observedcreate_financial_plan
    • First observedget_credit_health
    • First observedoptimize_loans
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 5 tools

Disambiguation4/5

Tools cover distinct financial domains: credit health, credit report analysis, portfolio analysis, loan optimization, and financial planning. The pair get_credit_health and analyze_credit_report have slight overlap but are differentiated by scope (summary vs. detailed report).

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_, analyze_, optimize_, create_), using present tense verbs and clear nouns.

Tool Count5/5

With 5 tools, the server is well-scoped for a personal finance assistant, covering key areas without being bloated or too sparse.

Completeness3/5

Core personal finance areas are covered (credit, portfolio, loans, planning), but missing potentially important features like budgeting, expense tracking, or tax planning, which are common in financial tools.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Finance Tracker MCP Server

    ID45
    A
    license
    Not graded
    quality
    D
    maintenance
    AI-powered personal finance analysis through Claude AI using Plaid integration, enabling natural language queries about transactions, subscriptions, budgets, and spending trends.
    1
    MIT

  • trading-skills

    staskh
    A
    license
    B
    quality
    A
    maintenance
    Provides 32 trading analysis tools for AI-powered market analysis, including real-time data, technical indicators, options Greeks, scanners, and Interactive Brokers portfolio management, all accessible via natural language in Claude Desktop.
    36
    364
    MIT

  • CRE Intelligence MCP

    Zwondra
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides live commercial real estate data (rates, demographics) and analysis tools (DCF, rent roll parsing, lease abstraction, IC memo generation) within Claude Desktop.
    1
    MIT