mcp server

telmus

Financial statement analysis for any stock. Piotroski, Altman Z, Beneish M - one command."

shubhwade/telmuscommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "telmus": {
      "command": "uvx",
      "args": [
        "telmus"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 26, 2026

telmus

Financial statement analysis for AI IDEs and coding agents.

pip install telmus
telmus scan INFY

What is telmus?

telmus is a Python package and CLI for parsing financial statements, computing key valuation and health ratios, and exposing them through an MCP server for AI tools.

Engines

Engine	What it measures	Key metric
Valuation	Price multiples and peer comparison	P/E, P/B, EV/EBITDA
Health	Balance sheet strength and bankruptcy risk	Piotroski F-score, Altman Z-score
Flags	Earnings quality and cash flow risk	Beneish M-score, free cash flow trend

analyst_brief

A deterministic summary field that explains fundamentals, growth, and red flags without using an LLM.

Example output:

{
  "analyst_brief": "Strong fundamentals (Piotroski F-score of 7). Financially safe (Altman Z-score of 4.20). Revenue growth is 11.2% over three years and operating margins are stable. No significant red flags detected. Suitable for DCF or comparable company analysis."
}

Quick start

Install:

pip install telmus

Scan a ticker:

telmus scan INFY

Read the summary and analyst brief, or export JSON for automation.

MCP server setup

{
  "mcpServers": {
    "telmus": {
      "command": "telmus",
      "args": ["serve"],
      "description": "Financial statement analysis — real ratios for any ticker"
    }
  }
}

Claude Desktop: use the config to register telmus as an MCP tool.
Cursor: same config loads telmus as a tool for market research.
Windsurf: connect the MCP server to get real financial metrics.

Other commands

Command	Description
`telmus scan TICKER`	Run a full financial scan
`telmus scan TICKER --json`	Print raw JSON
`telmus scan TICKER --export FILE.json`	Save JSON to a file
`telmus compare A B`	Compare two tickers
`telmus screen`	Run a simple sector screener
`telmus serve`	Start the MCP server
`telmus info`	Print package info
`telmus check TICKER`	Quick health check

Benchmark

Test	Result
Piotroski score coverage	9 signals
Altman Z distress detection	safe/grey/distress ranges
Flag detection	Beneish M, D/E, FCF trend

Architecture

yfinance -> loader -> valuation/health/growth/flags -> ScanResult -> CLI / MCP / SDK

Contributing

Fork the repository.
Create a feature branch.
Run pip install -e ."[dev]".
Write tests and update docs.
Submit a pull request.

License

MIT License