# https://github.com/sarveshtalele/personal-finance-mcp Project Manual

Generated on: 2026-05-22 17:34:17 UTC

## Table of Contents

- [Repository Overview](#overview)
- [Entrypoints and Runtime Surface](#entrypoints)
- [Architecture Evidence Map](#architecture)
- [Operations and Verification Boundaries](#operations)

<a id='overview'></a>

## Repository Overview

### Related Pages

Related topics: [Entrypoints and Runtime Surface](#entrypoints), [Architecture Evidence Map](#architecture), [Operations and Verification Boundaries](#operations)

<details>
<summary>Relevant source files</summary>

The following source files were used to generate this page:

- [Dockerfile](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/Dockerfile)
- [README.md](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/pyproject.toml)
- [src/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__init__.py)
- [src/__main__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__main__.py)
- [src/server.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/server.py)
- [src/models/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/__init__.py)
- [src/models/enums.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/enums.py)
- [src/models/schemas.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/schemas.py)
- [src/tools/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/__init__.py)
- [src/tools/bonds.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/bonds.py)
- [src/tools/debt.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/debt.py)
</details>

# Repository Overview

This page is generated from repository evidence because the Human Wiki provider was unavailable. It intentionally limits itself to README and file-tree facts.

## README Evidence

# 💰 Personal Finance MCP Server

mcp-name: io.github.sarveshtalele/personal-finance

> **Deterministic personal finance calculator** powered by [Model Context Protocol](https://modelcontextprotocol.io/) — based on the **Core Financial Principles**.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org)
[![MCP SDK](https://img.shields.io/badge/MCP-1.0+-blueviolet)](https://modelcontextprotocol.io/)
[![PyPI](https://img.shields.io/pypi/v/personal-finance-mcp?color=blue)](https://pypi.org/project/personal-finance-mcp/)
[![Tests](https://img.shields.io/badge/tests-100%25_passing-brightgreen)](tests/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## ✨ What It Does

Connect this server to **Claude Desktop**, **Claude Code**, or any MCP client to get **54 financial calculation tools** with:

- 🔢 **Deterministic outputs** — same inputs → same results, always
- 📖 **Theory-grounded** — every formula traced to core financial concepts
- 📐 **Full formula display** — shows the exact calculation, not just the answer
- 🇮🇳 **Indian finance context** — ₹ formatting, SIP planning, EMI calculations
- 🚀 **Zero external APIs** — works fully offline, no LLM dependency for math

---

## 📦 Quick Start

### 1. Connect to Claude Desktop (Zero-Install Method)

Because this tool is globally published to PyPI, you don't even need to download the code to use it. Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "personal-finance": {
      "command": "uvx",
      "args": [
        "personal-finance-mcp"
      ]
    }
  }
}
```

> **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
> **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

Restart Claude Desktop, and you will see the integration automatically.

### 2. Manual Global Installation

If you'd like to use it natively from your terminal without `uv`, just install it via standard `pip`:

```bash
pip install personal-finance-mcp

# Starts the server!
personal-finance-mcp
```

---

## 🛠 Tool Categories (54 Tools)

### 📊 Time Value of Money — 10 tools
| Tool | Description |
|------|-------------|
| `calculate_future_value` | FV with any compounding frequency |
| `calculate_present_value` | Discount future cash flows to today |
| `calculate_annuity_fv` | Future value of regular pa

[excerpt truncated]

## Selected Source Inventory

- `Dockerfile`
- `README.md`
- `pyproject.toml`
- `src/__init__.py`
- `src/__main__.py`
- `src/server.py`
- `src/models/__init__.py`
- `src/models/enums.py`
- `src/models/schemas.py`
- `src/tools/__init__.py`
- `src/tools/bonds.py`
- `src/tools/debt.py`

| File | Evidence role | Size |
|---|---|---|
| `Dockerfile` | repository evidence | 579 bytes |
| `README.md` | README/product and usage evidence | 12381 bytes |
| `pyproject.toml` | package/runtime metadata | 643 bytes |
| `src/__init__.py` | implementation surface | 0 bytes |
| `src/__main__.py` | implementation surface | 87 bytes |
| `src/server.py` | implementation surface | 1223 bytes |
| `src/models/__init__.py` | implementation surface | 63 bytes |
| `src/models/enums.py` | implementation surface | 1318 bytes |
| `src/models/schemas.py` | implementation surface | 6589 bytes |
| `src/tools/__init__.py` | implementation surface | 0 bytes |
| `src/tools/bonds.py` | implementation surface | 10055 bytes |
| `src/tools/debt.py` | implementation surface | 12777 bytes |

Source: `[README.md:1-120]()`

---

<a id='entrypoints'></a>

## Entrypoints and Runtime Surface

### Related Pages

Related topics: [Repository Overview](#overview), [Architecture Evidence Map](#architecture), [Operations and Verification Boundaries](#operations)

<details>
<summary>Relevant source files</summary>

The following source files were used to generate this page:

- [Dockerfile](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/Dockerfile)
- [README.md](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/pyproject.toml)
- [src/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__init__.py)
- [src/__main__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__main__.py)
- [src/server.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/server.py)
- [src/models/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/__init__.py)
- [src/models/enums.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/enums.py)
- [src/models/schemas.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/schemas.py)
- [src/tools/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/__init__.py)
- [src/tools/bonds.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/bonds.py)
- [src/tools/debt.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/debt.py)
</details>

# Entrypoints and Runtime Surface

The files below are the highest-signal candidates for how the project is installed, started, configured, or embedded. Treat this as an evidence map, not an inferred API contract.

| File | Evidence role | Size |
|---|---|---|
| `Dockerfile` | repository evidence | 579 bytes |
| `README.md` | README/product and usage evidence | 12381 bytes |
| `pyproject.toml` | package/runtime metadata | 643 bytes |
| `src/__init__.py` | implementation surface | 0 bytes |
| `src/__main__.py` | implementation surface | 87 bytes |
| `src/server.py` | implementation surface | 1223 bytes |
| `src/models/__init__.py` | implementation surface | 63 bytes |
| `src/models/enums.py` | implementation surface | 1318 bytes |
| `src/models/schemas.py` | implementation surface | 6589 bytes |
| `src/tools/__init__.py` | implementation surface | 0 bytes |
| `src/tools/bonds.py` | implementation surface | 10055 bytes |
| `src/tools/debt.py` | implementation surface | 12777 bytes |

Source: `[Dockerfile:1-120](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/Dockerfile)`

---

<a id='architecture'></a>

## Architecture Evidence Map

### Related Pages

Related topics: [Repository Overview](#overview), [Entrypoints and Runtime Surface](#entrypoints), [Operations and Verification Boundaries](#operations)

<details>
<summary>Relevant source files</summary>

The following source files were used to generate this page:

- [Dockerfile](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/Dockerfile)
- [README.md](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/pyproject.toml)
- [src/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__init__.py)
- [src/__main__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__main__.py)
- [src/server.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/server.py)
- [src/models/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/__init__.py)
- [src/models/enums.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/enums.py)
- [src/models/schemas.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/schemas.py)
- [src/tools/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/__init__.py)
- [src/tools/bonds.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/bonds.py)
- [src/tools/debt.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/debt.py)
</details>

# Architecture Evidence Map

This section maps source paths into likely architectural areas based on repository layout only. Claims that require execution are intentionally not made here.

- `.`: `Dockerfile`, `README.md`, `pyproject.toml`
- `src`: `src/__init__.py`, `src/__main__.py`, `src/server.py`, `src/models/__init__.py`, `src/models/enums.py`, `src/models/schemas.py`

Source: `[README.md:1-120](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/README.md)`

---

<a id='operations'></a>

## Operations and Verification Boundaries

### Related Pages

Related topics: [Repository Overview](#overview), [Entrypoints and Runtime Surface](#entrypoints), [Architecture Evidence Map](#architecture)

<details>
<summary>Relevant source files</summary>

The following source files were used to generate this page:

- [Dockerfile](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/Dockerfile)
- [README.md](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/README.md)
- [pyproject.toml](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/pyproject.toml)
- [src/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__init__.py)
- [src/__main__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/__main__.py)
- [src/server.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/server.py)
- [src/models/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/__init__.py)
- [src/models/enums.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/enums.py)
- [src/models/schemas.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/models/schemas.py)
- [src/tools/__init__.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/__init__.py)
- [src/tools/bonds.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/bonds.py)
- [src/tools/debt.py](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/src/tools/debt.py)
</details>

# Operations and Verification Boundaries

Operational guidance is limited to files that are present in the repository. Before using this project in an agent workflow, verify install, quickstart, and runtime behavior in a sandbox.

- Containerization signal: `Dockerfile`
- Documentation signal: `README.md`
- Runtime/package signal: `pyproject.toml`
- Source inspection signal: `src/__init__.py`
- Source inspection signal: `src/__main__.py`
- Source inspection signal: `src/server.py`
- Source inspection signal: `src/models/__init__.py`
- Source inspection signal: `src/models/enums.py`
- Source inspection signal: `src/models/schemas.py`
- Source inspection signal: `src/tools/__init__.py`

Source: `[pyproject.toml:1-120](https://github.com/sarveshtalele/personal-finance-mcp/blob/main/pyproject.toml)`

---

---

## Doramagic Pitfall Log

Project: sarveshtalele/personal-finance-mcp

Summary: Found 7 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 涉及密钥、隐私或敏感领域.

## 1. security_permissions · 涉及密钥、隐私或敏感领域

- Severity: high
- Evidence strength: source_linked
- Finding: 项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
- User impact: 金融、交易、隐私和密钥场景必须比普通工具更保守。
- Suggested check: 补敏感数据流、密钥存储和权限边界审查。
- Guardrail action: 敏感领域或密钥场景必须保守推荐并要求人工复核。
- Evidence: packet_text.keyword_scan | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | matched secret / private key / privacy / trading / finance keyword

## 2. capability · 能力判断依赖假设

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | README/documentation is current enough for a first validation pass.

## 3. maintenance · 维护活跃度未知

- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | last_activity_observed missing

## 4. security_permissions · 下游验证发现风险项

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | no_demo; severity=medium

## 5. security_permissions · 存在评分风险

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | no_demo; severity=medium

## 6. maintenance · issue/PR 响应质量未知

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | issue_or_pr_quality=unknown

## 7. maintenance · 发布节奏不明确

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.sarveshtalele/personal-finance:1.0.2 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.sarveshtalele%2Fpersonal-finance/versions/1.0.2 | release_recency=unknown

<!-- canonical_name: sarveshtalele/personal-finance-mcp; human_manual_source: deepwiki_human_wiki -->