{"id":34501508,"url":"https://github.com/cfdude/mcp-finnhub","last_synced_at":"2026-01-20T17:29:24.203Z","repository":{"id":327329721,"uuid":"1100094469","full_name":"cfdude/mcp-finnhub","owner":"cfdude","description":"Model Context Protocol server for Finnhub financial market data API","archived":false,"fork":false,"pushed_at":"2025-12-03T02:34:39.000Z","size":445,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T03:16:22.582Z","etag":null,"topics":["finnhub","mcp-server","pypi-package","python-3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cfdude.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-11-19T20:42:48.000Z","updated_at":"2025-12-03T02:21:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cfdude/mcp-finnhub","commit_stats":null,"previous_names":["cfdude/mcp-finnhub"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cfdude/mcp-finnhub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-finnhub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-finnhub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-finnhub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-finnhub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cfdude","download_url":"https://codeload.github.com/cfdude/mcp-finnhub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cfdude%2Fmcp-finnhub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27992996,"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-12-24T02:00:07.193Z","response_time":83,"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":["finnhub","mcp-server","pypi-package","python-3"],"created_at":"2025-12-24T02:02:18.423Z","updated_at":"2025-12-24T02:02:39.645Z","avatar_url":"https://github.com/cfdude.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-finnhub\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io)\n\nModel Context Protocol (MCP) server providing comprehensive access to [Finnhub](https://finnhub.io) financial market data API. Built for AI assistants like Claude Desktop to seamlessly access real-time market data, technical indicators, fundamentals, and alternative data.\n\n## Features\n\n- **15 MCP Tools** covering 100+ Finnhub API endpoints\n- **Real-time market data**: Quotes, candles, tick data, BBO\n- **Technical analysis**: 50+ indicators, patterns, support/resistance\n- **Fundamentals**: Financials, earnings, dividends, metrics\n- **Alternative data**: ESG scores, social sentiment, supply chain\n- **Multi-asset support**: Stocks, crypto, forex, ETFs, bonds\n- **Project-based storage** with automatic CSV/JSON exports\n- **Background job processing** for large datasets\n- **Smart output handling** with token estimation\n- **Configurable tools** - enable only what you need\n- **AI-friendly errors** - Structured error responses with guidance\n- **Built-in help** - Every tool supports `operation=\"help\"` for discovery\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11 or higher\n- [Finnhub API key](https://finnhub.io/register) (free tier available)\n- [Claude Desktop](https://claude.ai/download) or compatible MCP client\n\n### Installation\n\n#### Option 1: Install from PyPI (coming soon)\n\n```bash\npip install mcp-finnhub\n```\n\n#### Option 2: Install from source\n\n```bash\ngit clone https://github.com/cfdude/mcp-finnhub.git\ncd mcp-finnhub\npip install -e .\n```\n\n### Configuration\n\n1. Create a `.env` file in your project root:\n\n```bash\n# Required\nFINNHUB_API_KEY=your_api_key_here\nFINNHUB_STORAGE_DIR=/path/to/storage\n\n# Optional - Tool configuration\nFINNHUB_ENABLE_TECHNICAL_ANALYSIS=true\nFINNHUB_ENABLE_STOCK_MARKET_DATA=true\nFINNHUB_ENABLE_NEWS_SENTIMENT=true\n# ... enable/disable other tools as needed\n\n# Optional - Performance tuning\nFINNHUB_RATE_LIMIT_RPM=300  # Requests per minute (30 free, 300 premium)\nFINNHUB_REQUEST_TIMEOUT=30  # Request timeout in seconds\nFINNHUB_SAFE_TOKEN_LIMIT=75000  # Conservative token limit\n```\n\n2. Configure Claude Desktop to use mcp-finnhub by adding to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"finnhub\": {\n      \"command\": \"mcp-finnhub\",\n      \"env\": {\n        \"FINNHUB_API_KEY\": \"your_api_key_here\",\n        \"FINNHUB_STORAGE_DIR\": \"/Users/yourname/finnhub-data\"\n      }\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop\n\n### First Query\n\nAsk Claude:\n\n\u003e \"Get me the latest quote for AAPL\"\n\nClaude will use the `finnhub_stock_market_data` tool with the `get_quote` operation to fetch Apple's real-time stock quote.\n\n## Available Tools\n\n### Core Trading \u0026 Analysis (3 tools)\n\n- **`finnhub_stock_market_data`** - Quotes, candles, tick data, BBO, market status\n- **`finnhub_technical_analysis`** - 50+ indicators (RSI, MACD, SMA), patterns, signals\n- **`finnhub_news_sentiment`** - Company news, market news, sentiment scores\n\n### Fundamentals \u0026 Analysis (5 tools)\n\n- **`finnhub_stock_fundamentals`** - Financials, earnings, dividends, metrics\n- **`finnhub_stock_estimates`** - Revenue/EPS estimates, price targets\n- **`finnhub_stock_ownership`** - Insider trades, institutional holdings\n- **`finnhub_alternative_data`** - ESG scores, social sentiment, supply chain\n- **`finnhub_sec_filings`** - SEC filings, earnings transcripts\n\n### Multi-Asset Data (4 tools)\n\n- **`finnhub_crypto_data`** - Crypto exchanges, symbols, profiles, candles\n- **`finnhub_forex_data`** - Forex rates, candles, exchanges\n- **`finnhub_calendar_data`** - IPO calendar, earnings calendar, economic events\n- **`finnhub_market_events`** - Market holidays, analyst upgrades/downgrades\n\n### Management Tools (3 tools)\n\n- **`finnhub_project_create`** - Create project workspaces\n- **`finnhub_project_list`** - List all projects with statistics\n- **`finnhub_job_status`** - Check background job status\n\n## Example Workflows\n\n### Technical Analysis Workflow\n\n```\nUser: \"Analyze TSLA using RSI and MACD indicators\"\n\nClaude uses:\n1. finnhub_technical_analysis → get_indicator (operation=get_indicator, symbol=TSLA, indicator=rsi)\n2. finnhub_technical_analysis → get_indicator (operation=get_indicator, symbol=TSLA, indicator=macd)\n3. Analyzes both indicators and provides trading insights\n```\n\n### Fundamental Research Workflow\n\n```\nUser: \"Research MSFT - get financials, earnings, and analyst estimates\"\n\nClaude uses:\n1. finnhub_stock_fundamentals → get_basic_financials (operation=get_basic_financials, symbol=MSFT)\n2. finnhub_stock_fundamentals → get_earnings (operation=get_earnings, symbol=MSFT)\n3. finnhub_stock_estimates → get_earnings_estimates (operation=get_earnings_estimates, symbol=MSFT)\n4. Summarizes financial health and analyst outlook\n```\n\n### Multi-Asset Portfolio Workflow\n\n```\nUser: \"Create a project called 'my-portfolio', get quotes for AAPL, BTC-USD, and EUR/USD\"\n\nClaude uses:\n1. finnhub_project_create → create (operation=create, project=my-portfolio)\n2. finnhub_stock_market_data → get_quote (operation=get_quote, symbol=AAPL, project=my-portfolio)\n3. finnhub_crypto_data → get_crypto_profile (operation=get_crypto_profile, symbol=BINANCE:BTCUSDT)\n4. finnhub_forex_data → get_forex_rates (operation=get_forex_rates, base=EUR, project=my-portfolio)\n5. All data saved to /storage/my-portfolio/ with CSV exports\n```\n\n## Tool Configuration\n\nControl which tools are available to reduce context window usage:\n\n```bash\n# Disable tools you don't need\nFINNHUB_ENABLE_CRYPTO=false\nFINNHUB_ENABLE_FOREX=false\nFINNHUB_ENABLE_ALTERNATIVE_DATA=false\n\n# Core tools (always recommended)\nFINNHUB_ENABLE_STOCK_MARKET_DATA=true\nFINNHUB_ENABLE_TECHNICAL_ANALYSIS=true\nFINNHUB_ENABLE_NEWS_SENTIMENT=true\n```\n\n## Rate Limits\n\n- **Free tier**: 60 requests/minute\n- **Basic tier**: 150 requests/minute ($49.99/month)\n- **Premium tier**: 300 requests/minute\n- **Enterprise tier**: Custom limits\n\nmcp-finnhub automatically handles rate limiting with exponential backoff and retry logic.\n\n## AI Agent Features\n\n### Help/Discovery\n\nEvery tool supports `operation=\"help\"` to discover available operations:\n\n```python\nfinnhub_stock_fundamentals(operation=\"help\")\n# Returns all operations with required/optional params and examples\n```\n\n### Structured Errors\n\nErrors return actionable JSON instead of stack traces:\n\n```json\n{\n  \"error\": \"invalid_operation\",\n  \"message\": \"Operation 'get_data' not found\",\n  \"valid_operations\": [\"get_basic_financials\", \"get_dividends\", ...],\n  \"tool\": \"finnhub_stock_fundamentals\"\n}\n```\n\n## Storage Structure\n\nProjects are stored in subdirectories:\n\n```\nFINNHUB_STORAGE_DIR/\n├── my-portfolio/\n│   ├── .project.json         # Project metadata\n│   ├── candles/              # Historical price data\n│   ├── quotes/               # Real-time quotes\n│   ├── news/                 # News articles\n│   ├── fundamentals/         # Financial data\n│   ├── technical/            # Technical indicators\n│   └── jobs/                 # Background job results\n└── research-tech/\n    └── ...\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/cfdude/mcp-finnhub.git\ncd mcp-finnhub\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest --cov=mcp_finnhub --cov-report=term-missing\n\n# Lint and format\nruff check --fix .\nruff format .\n```\n\n### Running Locally\n\n```bash\n# Set environment variables\nexport FINNHUB_API_KEY=your_api_key\nexport FINNHUB_STORAGE_DIR=/tmp/finnhub-data\n\n# Run the MCP server\nmcp-finnhub\n```\n\nThe server will listen on stdin/stdout for JSON-RPC requests following the MCP protocol.\n\n### Testing with MCP Inspector\n\n```bash\n# Install MCP inspector\nnpm install -g @modelcontextprotocol/inspector\n\n# Test the server\nmcp-inspector mcp-finnhub\n```\n\n## Architecture\n\n- **ServerContext**: Dependency injection container managing client and utilities\n- **Tool Registry**: Dynamic tool registration with enable/disable support\n- **STDIO Transport**: JSON-RPC over stdin/stdout implementing MCP 2024-11-05\n- **Async Job Processing**: Background workers for large dataset operations\n- **Type Safety**: Pydantic models for all API requests/responses\n\nSee [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed design documentation.\n\n## API Reference\n\nSee [API.md](docs/API.md) for complete tool documentation with examples.\n\n## Troubleshooting\n\n### \"Authentication failed\" error\n- Verify your `FINNHUB_API_KEY` is correct\n- Check if your API key has expired\n- Ensure you haven't exceeded rate limits\n\n### \"Tool not found\" error\n- Check that the tool is enabled in your configuration\n- Verify tool names match exactly (case-sensitive)\n\n### Storage permission errors\n- Ensure `FINNHUB_STORAGE_DIR` exists and is writable\n- Check filesystem permissions\n\n### Rate limit errors\n- Reduce `FINNHUB_RATE_LIMIT_RPM` in your configuration\n- Upgrade to premium tier for higher limits\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## Acknowledgments\n\n- Built with [Model Context Protocol](https://modelcontextprotocol.io)\n- Powered by [Finnhub API](https://finnhub.io)\n- Inspired by [mcp-fred](https://github.com/robsherman/mcp-fred) patterns\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/mcp-finnhub/issues)\n- **Documentation**: [docs/](docs/)\n- **Finnhub API Docs**: [finnhub.io/docs/api](https://finnhub.io/docs/api)\n\n---\n\n**Made with ❤️ for the AI assistant ecosystem**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fmcp-finnhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcfdude%2Fmcp-finnhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcfdude%2Fmcp-finnhub/lists"}