{"id":31825853,"url":"https://github.com/codemug/aiofmp","last_synced_at":"2025-10-11T16:30:04.956Z","repository":{"id":316871891,"uuid":"1048037875","full_name":"codemug/aiofmp","owner":"codemug","description":"Async SDK for financialmodelingprep.com","archived":false,"fork":false,"pushed_at":"2025-09-27T08:31:41.000Z","size":470,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T09:30:47.865Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codemug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-31T19:22:21.000Z","updated_at":"2025-08-31T20:14:53.000Z","dependencies_parsed_at":"2025-09-27T09:30:49.898Z","dependency_job_id":"1373083a-8170-4ce1-8b91-647da2859c51","html_url":"https://github.com/codemug/aiofmp","commit_stats":null,"previous_names":["codemug/aiofmp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codemug/aiofmp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemug%2Faiofmp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemug%2Faiofmp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemug%2Faiofmp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemug%2Faiofmp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codemug","download_url":"https://codeload.github.com/codemug/aiofmp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codemug%2Faiofmp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007834,"owners_count":26084368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T16:30:03.426Z","updated_at":"2025-10-11T16:30:04.931Z","avatar_url":"https://github.com/codemug.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aiofmp\n\n[![PyPI Version](https://img.shields.io/pypi/v/aiofmp.svg?color=0A7BBB)](https://pypi.org/project/aiofmp/)\n\n**aiofmp** is a comprehensive Python SDK that provides seamless access to the Financial Modeling Prep API through an intuitive, category-based interface. Built with asyncio for high-performance concurrent operations, it offers:\n\n- **Complete FMP API Coverage**: Access to 22+ API categories including financial statements, market data, news, technical indicators, and more\n- **Async-First Design**: Built with asyncio for high-performance concurrent operations and non-blocking I/O\n- **MCP Server Integration**: Built-in Model Context Protocol server that exposes all FMP APIs as AI-friendly tools\n- **Type Safety**: Full type hints throughout the codebase for better IDE support and error prevention\n- **Clean Architecture**: Category-based organization that mirrors the FMP API structure\n- **Comprehensive Error Handling**: Robust error handling with custom exceptions and retry logic\n- **Rate Limiting**: Built-in rate limiting and retry logic to respect API limits\n- **AI-Ready**: MCP tools designed specifically for AI assistants with natural language prompts\n\n### Key Features\n\n- **22 API Categories**: Complete coverage of all FMP API endpoints\n- **Flexible Configuration**: Environment-based configuration for easy deployment\n- **160+ MCP Tools**: Every FMP API function exposed as an MCP tool for AI assistants\n- **Dual Transport Support**: Both STDIO and HTTP transport modes for MCP server\n- **Comprehensive Testing**: Full test coverage with 500+ unit tests\n- **Production Ready**: Built for reliability and performance in production environments\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- Financial Modeling Prep API key ([Get one here](https://site.financialmodelingprep.com/developer/docs/pricing))\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/aiofmp.git\ncd aiofmp\n\n# Install dependencies using uv (recommended)\nuv sync\n\n# Install the package in development mode\nuv pip install -e .\n\n# Or using pip\npip install -e .\n\n# Activate virtual environment (if using uv)\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n```\n\n## Usage\n\n### Basic Client Usage\n\n```python\nimport asyncio\nfrom aiofmp import FmpClient\n\nasync def main():\n    # Initialize client with your API key\n    client = FmpClient(api_key=\"your_api_key_here\")\n\n    # Use async context manager for automatic session management\n    async with client:\n        # Search for symbols\n        symbols = await client.search.symbols(\"AAPL\", limit=10)\n        print(f\"Found {len(symbols)} symbols\")\n\n        # Get company profile\n        profile = await client.company.profile(\"AAPL\")\n        print(f\"Company: {profile['companyName']}\")\n        \n        # Get financial statements\n        income_statement = await client.statements.income_statement(\"AAPL\", limit=5)\n        print(f\"Retrieved {len(income_statement)} periods of income statement data\")\n\n# Run the example\nasyncio.run(main())\n```\n\n### MCP Server Usage\n\nThe aiofmp package includes a built-in MCP server that exposes all FMP APIs as AI-friendly tools.\n\n#### Configuration\n\nSet up environment variables for MCP server configuration:\n\n```bash\n# Required: FMP API Key\nexport FMP_API_KEY=\"your_api_key_here\"\n\n# Optional: MCP Server Configuration\nexport MCP_TRANSPORT=\"stdio\"  # or \"http\"\nexport MCP_HOST=\"localhost\"   # for HTTP transport\nexport MCP_PORT=\"3000\"        # for HTTP transport\nexport MCP_LOG_LEVEL=\"INFO\"   # DEBUG, INFO, WARNING, ERROR\n```\n\n#### Running the MCP Server\n\n**STDIO Transport (for MCP clients like Claude Desktop):**\n```bash\naiofmp-mcp-server\n```\n\n**HTTP Transport (for web-based MCP clients):**\n```bash\naiofmp-mcp-server --transport http\n```\n\n**Custom Configuration:**\n```bash\naiofmp-mcp-server --transport http --host 0.0.0.0 --port 8080\n```\n\n**With API Key:**\n```bash\naiofmp-mcp-server --api-key your_api_key_here\n```\n\n**With Debug Logging:**\n```bash\naiofmp-mcp-server --log-level DEBUG\n```\n\n#### Claude Desktop Integration\n\nAdd to your Claude Desktop configuration (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"aiofmp\": {\n      \"command\": \"aiofmp-mcp-server\",\n      \"args\": [\"--api-key\", \"your_api_key_here\"]\n    }\n  }\n}\n```\n\n**Alternative with environment variable:**\n```json\n{\n  \"mcpServers\": {\n    \"aiofmp\": {\n      \"command\": \"aiofmp-mcp-server\",\n      \"env\": {\n        \"FMP_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### CLI Reference\n\nThe `aiofmp-mcp-server` command provides a user-friendly interface for running the MCP server:\n\n```bash\n# Basic usage\naiofmp-mcp-server\n\n# Show help\naiofmp-mcp-server --help\n\n# HTTP transport\naiofmp-mcp-server --transport http --host 0.0.0.0 --port 8080\n\n# With API key\naiofmp-mcp-server --api-key your_api_key_here\n\n# Debug logging\naiofmp-mcp-server --log-level DEBUG\n\n# All options\naiofmp-mcp-server --transport http --host localhost --port 3000 --log-level INFO --api-key your_key\n```\n\n**Command Options:**\n- `--transport`: Transport mode (`stdio` or `http`, default: `stdio`)\n- `--host`: Host for HTTP transport (default: `localhost`)\n- `--port`: Port for HTTP transport (default: `3000`)\n- `--log-level`: Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, default: `INFO`)\n- `--api-key`: FMP API key (can also be set via `FMP_API_KEY` environment variable)\n\n### Available API Categories\n\nThe aiofmp client provides access to 22+ FMP API categories:\n\n- **Analyst**: Financial estimates, ratings, price targets, and analyst recommendations\n- **Calendar**: Earnings, dividends, IPOs, and economic events\n- **Chart**: Historical price data and technical analysis\n- **Company**: Company profiles, key metrics, and corporate information\n- **Commodity**: Commodity prices, quotes, and historical data\n- **COT**: Commitment of Traders reports for commodities\n- **Crypto**: Cryptocurrency prices, quotes, and market data\n- **DCF**: Discounted Cash Flow valuations and analysis\n- **Directory**: Symbol lists, exchanges, sectors, and reference data\n- **Economics**: Economic indicators, treasury rates, and macro data\n- **ETF**: ETF holdings, performance, and analysis\n- **Forex**: Foreign exchange rates and currency data\n- **Form 13F**: Institutional holdings and filings\n- **Indexes**: Stock market indices and performance\n- **Insider Trades**: Insider trading activity and statistics\n- **Market Performance**: Sector performance, market movers, and P/E ratios\n- **News**: Financial news, press releases, and market updates\n- **Quote**: Real-time quotes, price changes, and market data\n- **Search**: Symbol search, company search, and stock screening\n- **Senate**: Congressional trading disclosures and activity\n- **Statements**: Financial statements, ratios, and metrics\n- **Technical Indicators**: Moving averages, RSI, and technical analysis tools\n\n## Examples\n\n### Client Examples\n\nThe `examples/` directory contains comprehensive examples for each API category:\n\n```bash\n# Run specific examples\npython examples/fmp_search_example.py\npython examples/fmp_company_example.py\npython examples/fmp_statements_example.py\npython examples/fmp_technical_indicators_example.py\n```\n\n### MCP Server Examples\n\n**Example 1: Basic MCP Tool Usage**\n```python\n# These are example prompts that would be sent to an AI assistant using the MCP server\n\"What is the current stock quote for Apple (AAPL)?\"\n\"Show me the 20-day Simple Moving Average for Microsoft (MSFT)\"\n\"Get the latest financial statements for Tesla (TSLA)\"\n```\n\n**Example 2: Advanced Financial Analysis**\n```python\n# Complex analysis prompts\n\"Compare the P/E ratios of Apple, Microsoft, and Google over the past year\"\n\"Find all technology stocks with market cap over $100 billion\"\n\"Show me the insider trading activity for Tesla in the last 3 months\"\n```\n\n**Example 3: Market Research**\n```python\n# Market research prompts\n\"What are the biggest gainers in the market today?\"\n\"Show me the sector performance for the technology sector\"\n\"Get the latest earnings calendar for next week\"\n```\n\n### Example Files\n\n- `fmp_analyst_example.py` - Analyst estimates and ratings\n- `fmp_calendar_example.py` - Earnings and dividend calendars\n- `fmp_chart_example.py` - Historical price data\n- `fmp_company_example.py` - Company profiles and metrics\n- `fmp_commodity_example.py` - Commodity prices and data\n- `fmp_cot_example.py` - Commitment of Traders reports\n- `fmp_crypto_example.py` - Cryptocurrency data\n- `fmp_dcf_example.py` - DCF valuations\n- `fmp_directory_example.py` - Symbol lists and reference data\n- `fmp_economics_example.py` - Economic indicators\n- `fmp_etf_example.py` - ETF analysis\n- `fmp_forex_example.py` - Foreign exchange data\n- `fmp_form13f_example.py` - Institutional holdings\n- `fmp_indexes_example.py` - Market indices\n- `fmp_insider_trades_example.py` - Insider trading\n- `fmp_search_example.py` - Symbol and company search\n- `fmp_statements_example.py` - Financial statements\n\n### MCP Server Testing\n\nTest the MCP server functionality:\n\n```bash\n# Run all MCP tests\nuv run pytest tests/test_mcp_tools.py tests/test_mcp_server.py -v\n\n# Run specific category tests\nuv run pytest tests/test_mcp_tools.py::TestSearchTools -v\nuv run pytest tests/test_mcp_server.py::TestMCPServer -v\n\n# Test with debug logging\naiofmp-mcp-server --log-level DEBUG\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `FMP_API_KEY` | Financial Modeling Prep API key | None | Yes |\n| `MCP_TRANSPORT` | MCP server transport mode | `stdio` | No |\n| `MCP_HOST` | MCP server host (HTTP mode) | `localhost` | No |\n| `MCP_PORT` | MCP server port (HTTP mode) | `3000` | No |\n| `MCP_LOG_LEVEL` | Logging level | `INFO` | No |\n\n### MCP Server Modes\n\n**STDIO Mode (Default):**\n- Used by MCP clients like Claude Desktop\n- Communicates via standard input/output\n- No network configuration required\n\n**HTTP Mode:**\n- Used by web-based MCP clients\n- Requires host and port configuration\n- Supports multiple concurrent connections\n\n## API Reference\n\n### Client Categories\n\nEach API category provides methods that mirror the FMP API structure:\n\n```python\n# Search and discovery\nawait client.search.symbols(\"AAPL\")\nawait client.search.companies(\"Apple\")\nawait client.search.screener(sector=\"Technology\")\n\n# Company information\nawait client.company.profile(\"AAPL\")\nawait client.company.key_metrics(\"AAPL\")\n\n# Financial statements\nawait client.statements.income_statement(\"AAPL\")\nawait client.statements.balance_sheet(\"AAPL\")\nawait client.statements.cash_flow_statement(\"AAPL\")\n\n# Market data\nawait client.quote.stock_quote(\"AAPL\")\nawait client.chart.historical_price_full(\"AAPL\")\n\n# Technical analysis\nawait client.technical_indicators.simple_moving_average(\"AAPL\", 20, \"1day\")\nawait client.technical_indicators.relative_strength_index(\"AAPL\", 14, \"1day\")\n```\n\n### MCP Tools\n\nThe MCP server exposes 160+ tools across all categories. Each tool includes:\n- Detailed descriptions and parameter documentation\n- Natural language examples for AI assistants\n- Comprehensive error handling\n- Type validation and parameter checking\n\n## Error Handling\n\nThe client includes comprehensive error handling:\n\n```python\nfrom aiofmp.exceptions import FmpError, FmpRateLimitError, FmpAPIError\n\ntry:\n    data = await client.search.symbols(\"INVALID\")\nexcept FmpAPIError as e:\n    print(f\"API Error: {e}\")\nexcept FmpRateLimitError as e:\n    print(f\"Rate limit exceeded: {e}\")\nexcept FmpError as e:\n    print(f\"General error: {e}\")\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test categories\nuv run pytest tests/test_search.py -v\nuv run pytest tests/test_mcp_tools.py -v\n\n# Run with coverage\nuv run pytest --cov=aiofmp --cov-report=html\n```\n\n## Performance\n\n- **Async Operations**: All API calls are non-blocking\n- **Connection Pooling**: Efficient HTTP connection management\n- **Rate Limiting**: Built-in rate limiting to respect API limits\n- **Caching**: Optional response caching for improved performance\n- **Concurrent Requests**: Support for multiple simultaneous API calls\n\n## Security\n\n- **API Key Management**: Secure handling of API keys\n- **Environment Variables**: Support for environment-based configuration\n- **No Hardcoded Secrets**: All sensitive data via configuration\n- **HTTPS Only**: All API communications over secure connections\n\n## Release Process\n\nThis project uses [Semantic Release](https://semantic-release.gitbook.io/) for automated versioning and publishing. The release process is fully automated through GitHub Actions.\n\n### How It Works\n\n1. **Conventional Commits**: All commits must follow the [Conventional Commits](https://conventionalcommits.org/) specification\n2. **Automatic Versioning**: Semantic Release analyzes commit messages to determine the next version\n3. **Automatic Publishing**: When a new version is detected, it automatically:\n   - Creates a git tag\n   - Updates the CHANGELOG.md\n   - Publishes to PyPI\n   - Creates a GitHub release\n\n### Commit Message Format\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n\n\u003cbody\u003e\n\n\u003cfooter\u003e\n```\n\n**Types:**\n- `feat`: New features\n- `fix`: Bug fixes\n- `docs`: Documentation changes\n- `style`: Code style changes (formatting, etc.)\n- `refactor`: Code refactoring\n- `perf`: Performance improvements\n- `test`: Test additions or changes\n- `chore`: Build process or auxiliary tool changes\n\n**Examples:**\n```bash\nfeat(mcp): add new search tools for financial data\nfix(api): resolve authentication error in client\ndocs: update installation instructions\ntest: add unit tests for MCP server\nchore: update dependencies\n```\n\n### Setting Up Releases\n\n1. **Configure Git** (run once):\n   ```bash\n   ./scripts/setup-git.sh\n   ```\n\n2. **Set up PyPI Token**:\n   - Go to [PyPI Account Settings](https://pypi.org/manage/account/)\n   - Create an API token\n   - Add it to GitHub Secrets as `PYPI_API_TOKEN`\n\n3. **Update Repository URLs**:\n  - Update URLs in `pyproject.toml`\n  - Update author information\n\n4. **Make Changes and Commit**:\n   ```bash\n   git add .\n   git commit -m \"feat: add new feature\"\n   git push origin main\n   ```\n\nThe GitHub Action will automatically:\n- Run quick tests and linting\n- Check code quality\n- Determine if a release is needed\n- Create a new version and publish to PyPI\n\n### Manual Testing\n\nFor comprehensive testing, you can manually trigger the test workflow:\n\n1. Go to the \"Actions\" tab in your GitHub repository\n2. Select the \"Test\" workflow\n3. Click \"Run workflow\"\n4. Choose:\n   - **Python version**: 3.10, 3.11, 3.12, or 3.13\n   - **Test type**: all, unit, mcp, or integration\n5. Click \"Run workflow\"\n\nThis allows you to run tests on specific Python versions or test categories without using your free tier minutes unnecessarily.\n\n## Contributing\n\nContributions are welcome! We appreciate any help in improving aiofmp.\n\n### Development Setup\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/your-username/aiofmp.git\ncd aiofmp\nuv sync --dev\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check .\nuv run ruff format .\n```\n\n### Contribution Guidelines\n\n1. **Fork the repository** and create a feature branch\n2. **Follow the coding standards** (type hints, docstrings, error handling)\n3. **Add comprehensive tests** for new functionality\n4. **Update documentation** for any API changes\n5. **Ensure all tests pass** before submitting a PR\n6. **Use conventional commits** for commit messages\n\n### Areas for Contribution\n\n- **New API Endpoints**: Add support for new FMP API endpoints\n- **Performance Improvements**: Optimize existing functionality\n- **Documentation**: Improve examples and documentation\n- **Testing**: Add more comprehensive test coverage\n- **MCP Tools**: Enhance MCP tool descriptions and examples\n- **Error Handling**: Improve error messages and handling\n\n### Reporting Issues\n\nPlease report bugs and request features through GitHub Issues. Include:\n- Python version and operating system\n- Steps to reproduce the issue\n- Expected vs actual behavior\n- Relevant error messages and logs\n\n## License\n\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Financial Modeling Prep](https://financialmodelingprep.com/) for providing the comprehensive financial data API\n- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework\n- The Python asyncio community for excellent async programming tools\n\n## Support\n\n- **Documentation**: Check the examples directory and inline docstrings\n- **Issues**: Report bugs and request features via GitHub Issues\n- **Discussions**: Use GitHub Discussions for questions and community support\n- **API Reference**: Full API documentation available in the code\n\n---\n\n**Built with ❤️ for the financial data community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemug%2Faiofmp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodemug%2Faiofmp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodemug%2Faiofmp/lists"}