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

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

1. Install:

pip install telmus

2. Scan a ticker:

telmus scan INFY

3. 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

Benchmark

Architecture

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

Contributing

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

License

MIT License