Metadata-Version: 2.4
Name: finpy-mcp
Version: 0.7.2
Summary: Finpy MCP Server — AI-powered asset management through conversation
Keywords: mcp,finpy,asset-management,cap-table,portfolio,ai,claude,llm
Author: Robert Radoslav
Author-email: Robert Radoslav <43938206+rbtrsv@users.noreply.github.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: click>=8.4.2
Requires-Dist: fastmcp>=3.4.4
Requires-Dist: httpx>=0.28.1
Requires-Python: >=3.12
Project-URL: Documentation, https://www.finpy.tech
Project-URL: Homepage, https://www.finpy.tech
Project-URL: PyPI, https://pypi.org/project/finpy-mcp/
Description-Content-Type: text/markdown

# finpy-mcp

**Finpy MCP Server** — Manage cap tables, deals, holdings, and financials through AI conversation.

Connect your favorite AI tool (Claude Desktop, Cursor, VS Code, Claude Code) to the [Finpy](https://www.finpy.tech) platform and work with your financial data through natural language.

## Features

- **76 asset management tools** plus 13 Factor Markets tools (89 total)
- **Cap table management** — stakeholders, funding rounds, securities, transactions
- **Deal flow** — create deals, express interest, execute fundraising rounds
- **Portfolio tracking** — holdings, valuations, performance metrics (IRR, MOIC, TVPI)
- **Financial reporting** — income statements, balance sheets, cash flow statements
- **Secure** — OAuth device flow login, credentials stored locally, no passwords sent to AI

## Quick Start

### 1. Install

```bash
pip install finpy-mcp
```

Or with uv:

```bash
# Install uv (if not already installed)
brew install uv

# Add uv tools to PATH (one-time setup)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Install finpy-mcp
uv tool install finpy-mcp
```

Already installed? Update:

```bash
pip install --upgrade finpy-mcp
# or
uv tool upgrade finpy-mcp
```

### 2. Login

```bash
finpy-cli login
```

Opens your browser automatically. Sign in on the Finpy web app, then return to your terminal.

### 3. Configure your AI client

**Claude Desktop** — Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "finpy": {
      "command": "finpy-mcp"
    }
  }
}
```

**Cursor** — Edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "finpy": {
      "command": "finpy-mcp"
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add finpy -- finpy-mcp
```

Restart your AI client after configuring.

### 4. Start talking

Open a new conversation and say:

- *"List my entities"*
- *"Show me the cap table for Nexotype"*
- *"Create a stakeholder John Doe as limited partner with 8% preferred return"*
- *"Create an income statement for 2026 with $1M revenue"*

## Available Tools (89)

Asset Manager tools are stateless: discover IDs with `list_organizations()` / `list_entities()`,
then pass `entity_id` (and `organization_id` for `create_entity`) explicitly to each tool. There
is no `set_context` — scope is an argument on every call. For the full per model capability map
(which operations are exposed, and why some are web only), see documentation/capability-matrix.md.

| Category | Tools |
|----------|-------|
| **Context** | list_organizations, list_entities, get_entity_details |
| **Entity** | create_entity, update_entity |
| **Cap Table** | list_stakeholders, create_stakeholder, update_stakeholder, list_funding_rounds, create_funding_round, list_securities, create_security, list_transactions, create_transaction, reverse_transaction, get_cap_table, list_commitments, list_positions, list_distributions |
| **Deals** | list_deals, create_deal, update_deal, update_deal_status, list_deal_commitments, express_interest, execute_deal |
| **Holdings** | list_holdings, create_holding, update_holding, list_valuations, create_valuation, update_valuation, delete_valuation, list_holding_cash_flows, create_holding_cash_flow, reverse_holding_cash_flow, list_deal_pipeline, create_pipeline_entry, update_pipeline_entry, delete_pipeline_entry, get_entity_performance, get_holdings_performance, get_stakeholder_returns |
| **Financials** | create_income_statement, update_income_statement, delete_income_statement, create_balance_sheet, update_balance_sheet, delete_balance_sheet, create_cash_flow_statement, update_cash_flow_statement, delete_cash_flow_statement, create_financial_metrics, update_financial_metrics, delete_financial_metrics, list_kpis, create_kpi, update_kpi, list_kpi_values, create_kpi_value, update_kpi_value, delete_kpi_value |
| **Fees** | list_fees, create_fee, update_fee, delete_fee |
| **Audit** | list_audit_trail, list_entity_audit_trail |
| **Factor Markets** | list_factormarkets_valuations, get_factormarkets_valuation, list_factormarkets_income_statements, list_factormarkets_balance_sheets, list_factormarkets_cash_flow_statements, list_backtest_results, and 7 more backtest tools |

## CLI Commands

```bash
finpy-cli login          # Login via browser (OAuth device flow)
finpy-cli login --basic  # Login with email/password (headless fallback)
finpy-cli logout         # Delete stored credentials
finpy-cli status         # Show auth status
```

## Security

- Passwords never reach the AI — login happens in your browser
- Credentials stored locally in `~/.finpy/credentials.json` (chmod 600)
- Automatic token refresh on expiry
- Delete is a soft delete only: the row is kept and can be restored from the web Trash page. MCP exposes delete on 8 leaf records without side effects (destructiveHint set); ledgers are reversed, never deleted. See documentation/capability-matrix.md.
- All API validations, permissions, and audit logging apply

## Requirements

- Python 3.12+
- A [Finpy](https://www.finpy.tech) account

## Links

- [Finpy Platform](https://www.finpy.tech)
- [PyPI Package](https://pypi.org/project/finpy-mcp/)
