{"id":"36d6aa2c-ff4b-4f36-8854-bed9821b1a44","slug":"telmus","kind":"mcp","name":"telmus","summary":"Financial statement analysis for any stock. Piotroski, Altman Z, Beneish M - one command.\"","owner":"shubhwade","repoUrl":"https://github.com/shubhwade/telmus","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-19T09:18:30.000Z","addedAt":"2026-10-21T17:36:02.299Z","logoUrl":"https://avatars.githubusercontent.com/u/209016661?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T01:17:08.569Z","sample":false,"url":"https://conduits.dev/tools/telmus","language":"Python","transports":["stdio"],"install":{"pypi":"telmus"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# telmus\n\n[![PyPI version](https://img.shields.io/pypi/v/telmus)](https://pypi.org/project/telmus/)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/telmus?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/telmus)\n[![Python](https://img.shields.io/pypi/pyversions/telmus)](https://pypi.org/project/telmus/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nFinancial statement analysis for AI IDEs and coding agents.\n\n```bash\npip install telmus\ntelmus scan INFY\n```\n\n## What is telmus?\n\ntelmus 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.\n\n## Engines\n\n| Engine | What it measures | Key metric |\n|---|---|---|\n| Valuation | Price multiples and peer comparison | P/E, P/B, EV/EBITDA |\n| Health | Balance sheet strength and bankruptcy risk | Piotroski F-score, Altman Z-score |\n| Flags | Earnings quality and cash flow risk | Beneish M-score, free cash flow trend |\n\n## analyst_brief\n\nA deterministic summary field that explains fundamentals, growth, and red flags without using an LLM.\n\nExample output:\n\n```json\n{\n  \"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.\"\n}\n```\n\n## Quick start\n\n1. Install:\n\n```bash\npip install telmus\n```\n\n2. Scan a ticker:\n\n```bash\ntelmus scan INFY\n```\n\n3. Read the summary and analyst brief, or export JSON for automation.\n\n## MCP server setup\n\n```json\n{\n  \"mcpServers\": {\n    \"telmus\": {\n      \"command\": \"telmus\",\n      \"args\": [\"serve\"],\n      \"description\": \"Financial statement analysis — real ratios for any ticker\"\n    }\n  }\n}\n```\n\n- Claude Desktop: use the config to register telmus as an MCP tool.\n- Cursor: same config loads telmus as a tool for market research.\n- Windsurf: connect the MCP server to get real financial metrics.\n\n## Other commands\n\n| Command | Description |\n|---|---|\n| `telmus scan TICKER` | Run a full financial scan |\n| `telmus scan TICKER --json` | Print raw JSON |\n| `telmus scan TICKER --export FILE.json` | Save JSON to a file |\n| `telmus compare A B` | Compare two tickers |\n| `telmus screen` | Run a simple sector screener |\n| `telmus serve` | Start the MCP server |\n| `telmus info` | Print package info |\n| `telmus check TICKER` | Quick health check |\n\n## Benchmark\n\n| Test | Result |\n|---|---|\n| Piotroski score coverage | 9 signals |\n| Altman Z distress detection | safe/grey/distress ranges |\n| Flag detection | Beneish M, D/E, FCF trend |\n\n## Architecture\n\n```\nyfinance -> loader -> valuation/health/growth/flags -> ScanResult -> CLI / MCP / SDK\n```\n\n## Contributing\n\n1. Fork the repository.\n2. Create a feature branch.\n3. Run `pip install -e .\"[dev]\"`.\n4. Write tests and update docs.\n5. Submit a pull request.\n\n## License\n\nMIT License\n"}