Skip to main content
Glama
fin-copilot-mcp

fin-copilot-mcp

by JediPercy

Multi-Agent Financial Analytics Copilot (fin-copilot-mcp)

CI/CD Pipeline Python 3.11+ Code Style: Ruff License: MIT

An enterprise-grade, deterministic multi-agent financial analytics engine built on Anthropic's Model Context Protocol (MCP) and Claude 3.5 Sonnet. The system processes complex natural language financial queries, translates them into dialect-validated PostgreSQL / DuckDB SQL, pulls live telemetry/market data, and executes a self-healing verification loop before presenting synthesized results.


πŸ— Architecture & Agent Topology

The system uses specialized, domain-isolated agents decoupled from underlying tools using MCP JSON-RPC protocol standards.

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚       User Query Interface / API       β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                         β”‚
                                         β–Ό
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Orchestrator Agent (Claude 3.5 Sonnet)  β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                         β”‚
         β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
         β”‚ (MCP Protocol)                β”‚ (MCP Protocol)                β”‚ (MCP Protocol)
         β–Ό                               β–Ό                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  mcp-server-sql  β”‚           β”‚mcp-server-stripe β”‚           β”‚mcp-server-market β”‚
β”‚ (PostgreSQL/Duck)β”‚           β”‚  (Billing Specs) β”‚           β”‚ (YFinance API)   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚
         β”‚ (Execution Error)
         β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  Self-Healing    β”‚ ── (Retry Stack Trace) ──► [ Orchestrator Agent ]
β”‚  Validation Loop β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Related MCP server: octagon-mcp-server

πŸ”‘ Key Features

  • MCP-Native Architecture: Fully decoupled tool servers using standard JSON-RPC over stdio / Server-Sent Events (SSE).

  • Self-Healing Text-to-SQL Loop: Runs deterministic dry-run verification (EXPLAIN) before execution. Automatically captures AST/syntax errors and feeds stack traces back to Claude for up to 3 repair retries.

  • Double-Entry Validation: Micro-agent verifying mathematical consistency, row cross-totals, and currency alignment prior to output synthesis.

  • Strict Type & Schema Safety: Runtime validation via Pydantic v2 and static type checking with MyPy.

  • Cross-Platform Developer Experience: Powers setup, linting, formatting, and testing on Windows (via PowerShell / py) and Linux/macOS seamlessly.


πŸ›  Tech Stack

Component

Technology

Purpose

LLM / Reasoning

Claude 3.5 Sonnet (anthropic)

Intent decomposition, tool orchestration, and SQL generation

Protocol Layer

FastMCP / Model Context Protocol

Standardized tool/resource encapsulation over JSON-RPC

Analytical Engine

PostgreSQL / DuckDB / SQLite

OLAP/OLTP query execution, AST validation, and schema inspection

Market Data

Yahoo Finance (yfinance)

Macroeconomic benchmarks, equity quotes, and volume metrics

Configuration

pydantic-settings

Type-safe environment management and secret handling

Developer Tooling

uv / pip, ruff, mypy, pytest

Hermetic builds, linting, typing, and testing


πŸ“ Repository Structure

fin-copilot-mcp/
β”œβ”€β”€ .github/
β”‚   └── workflows/
β”‚       └── ci.yml                 # CI pipeline (lint, type-check, unit & integration tests)
β”œβ”€β”€ config/
β”‚   └── mcp_servers.json          # System tool topologies and connection mappings
β”œβ”€β”€ docker/
β”‚   β”œβ”€β”€ Dockerfile.orchestrator    # Production container for agent runtime
β”‚   └── Dockerfile.mcp-server      # Container specification for standalone MCP servers
β”œβ”€β”€ src/
β”‚   └── fin_copilot/
β”‚       β”œβ”€β”€ core/                  # Base configuration, logging, exceptions
β”‚       β”œβ”€β”€ mcp_servers/           # Standalone FastMCP server modules (SQL, Stripe, Market)
β”‚       β”œβ”€β”€ agents/                # Orchestrator agent logic, prompts, and healing loops
β”‚       └── utils/                 # Telemetry and formatting helpers
β”œβ”€β”€ tests/
β”‚   β”œβ”€β”€ unit/                      # FastMCP tool & resource unit tests
β”‚   β”œβ”€β”€ integration/               # Multi-agent self-healing loop tests
β”‚   └── evals/                     # Benchmarks for Text-to-SQL translation accuracy
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ setup.ps1                  # Windows PowerShell setup script
β”‚   └── setup.sh                   # Linux / macOS bash setup script
β”œβ”€β”€ pyproject.toml                 # Packaging, dependencies, and linter rules
β”œβ”€β”€ .gitignore                     # Industry-standard Python ignore rules
β”œβ”€β”€ .env.example                   # Environment variable template
└── README.md

πŸš€ Quickstart

Prerequisites

  • Python >= 3.11

  • uv or standard pip

  • Anthropic API Key (ANTHROPIC_API_KEY)

Installation & Setup

On Windows (PowerShell):

# 1. Clone the repository
git clone https://github.com/your-username/fin-copilot-mcp.git
cd fin-copilot-mcp

# 2. Run PowerShell Setup Script
.\scripts\setup.ps1

# 3. Configure environment variables
Copy-Item .env.example .env

On Linux / macOS (Bash):

# 1. Clone the repository
git clone https://github.com/your-username/fin-copilot-mcp.git
cd fin-copilot-mcp

# 2. Run Setup Script
chmod +x ./scripts/setup.sh
./scripts/setup.sh

# 3. Configure environment variables
cp .env.example .env

πŸ›‘ Security & Guardrails

  • Read-Only Database Connections: SQL MCP server limits execution strictly to SELECT statements and dialect dry-runs.

  • Token Sandboxing: API keys are isolated within environment settings classes and never exposed across tool execution boundaries.

  • Data Masking: Structural masking applied to sensitive financial attributes prior to model context generation.


πŸ“œ License

Distributed under the MIT License. See LICENSE for details.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables natural-language financial research and analysis across public filings, earnings transcripts, financial metrics, stock and crypto market data, and prediction markets, returning structured, source-backed answers within MCP clients.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables natural-language questions and structured, source-backed answers across SEC filings, earnings transcripts, company financials, stock and crypto market data, and prediction markets news and research, with orchestration, deep-research agents, and live documentation access.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to perform variance analysis, generate reconciling driver bridges and three-statement forecasts, export Excel workbooks, and analyze SEC or private-company financial data locally with engine-verified calculations.
      MIT