内容
# 🇨🇮 BRVM MCP Server
**The first MCP server for West Africa's regional stock exchange.**
Connect any AI agent — Claude, ChatGPT, Cursor, Copilot, LangGraph — to live market data from the [BRVM](https://www.brvm.org/) (Bourse Régionale des Valeurs Mobilières), serving 8 UEMOA member states across West Africa.
---
## Why?
The BRVM lists ~46 companies across Bénin, Burkina Faso, Côte d'Ivoire, Guinée-Bissau, Mali, Niger, Sénégal, and Togo — with a combined market cap of ~$27.8B USD. Yet it has **no public API**. This server bridges that gap, making BRVM data accessible to the AI ecosystem via the [Model Context Protocol](https://modelcontextprotocol.io).
### What's coming on the BRVM
- **December 18, 2026**: First derivatives market in francophone West Africa (futures on indices and stocks)
- **2026–2027**: ETF listings
- **2026**: Agricultural commodities exchange (BMPA CI) — cashew, maize, cola nut
This server is built to grow alongside these developments.
## Features
### Tools (7)
| Tool | Description |
|------|-------------|
| `get_market_summary` | Full trading session overview: volume, value, gainers/losers, indices |
| `get_stock_price` | Current quote for a specific ticker (price, change, volume) |
| `get_indices` | All BRVM indices: Composite, BRVM 30, Prestige, Principal, sectors |
| `get_top_movers` | Top N gainers and losers of the day |
| `get_company_info` | Company details: name, country, sector, market cap |
| `search_stocks` | Search by name, country, or sector |
| `list_tickers` | All ~46 BRVM tickers with metadata |
### Resources
| URI | Description |
|-----|-------------|
| `brvm://about` | BRVM exchange overview for context injection |
### Prompts
| Prompt | Description |
|--------|-------------|
| `analyze_stock` | Structured analysis of a BRVM stock |
| `market_report` | Full daily market report template |
## Quick Start
### Prerequisites
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
### Install & Run
```bash
# Clone
git clone https://github.com/dilanefk/brvm-mcp-server.git
cd brvm-mcp-server
# Install
uv sync
# Run (stdio — for Claude Desktop / Cursor)
uv run brvm-mcp
# Run (HTTP — for remote agents / web apps)
uv run brvm-mcp --transport streamable-http --port 8000
```
### Connect to Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"brvm": {
"command": "uv",
"args": ["run", "--directory", "/path/to/brvm-mcp-server", "brvm-mcp"]
}
}
}
```
Restart Claude Desktop. You'll see the BRVM tools in the 🔨 menu.
### Test with MCP Inspector
```bash
npx @modelcontextprotocol/inspector uv run brvm-mcp
```
### Docker (remote deployment)
```bash
docker build -t brvm-mcp .
docker run -p 8000:8000 brvm-mcp
```
## Example Conversations
Once connected, you can ask Claude:
> *"What's the BRVM market doing today?"*
> → Calls `get_market_summary()`, returns full session data
> *"Show me Sonatel's stock price"*
> → Calls `get_stock_price("SNTS")`
> *"Which BRVM stocks are from Sénégal?"*
> → Calls `search_stocks(country="Sénégal")`
> *"Give me a full market report"*
> → Uses the `market_report` prompt to orchestrate multiple tool calls
> *"Which stocks dropped the most today?"*
> → Calls `get_top_movers()`, focuses on losers
## Architecture
```
┌──────────────────┐ MCP (stdio/HTTP) ┌──────────────────┐
│ AI Agent │◄────────────────────────►│ BRVM MCP Server │
│ (Claude, GPT, │ │ │
│ Cursor, etc.) │ │ FastMCP + Tools │
└──────────────────┘ │ + Cache Layer │
└────────┬─────────┘
│ httpx
┌────────▼─────────┐
│ Data Sources │
│ • afx.kwayisi │
│ • brvm.org │
│ • Rich Bourse │
└──────────────────┘
```
- **FastMCP**: Decorator-based MCP framework (official Python SDK)
- **httpx**: Async HTTP client for scraping
- **BeautifulSoup4 + lxml**: HTML parsing
- **diskcache**: TTL-based disk caching (5min default, respectful of sources)
- **Pydantic**: Structured data models
## Roadmap
- [ ] **v0.2** — Historical price data (OHLCV bars)
- [ ] **v0.3** — BRVM official announcements / corporate actions feed
- [ ] **v0.4** — BMPA CI commodities data (when available)
- [ ] **v0.5** — Derivatives data (futures, options — post Dec 2026 launch)
- [ ] **v1.0** — OAuth + rate limiting for multi-user deployment
- [ ] Register on [MCP Registry](https://registry.modelcontextprotocol.io)
## Data Sources & Fair Use
This server scrapes publicly available data. It implements:
- **Caching** (5min TTL) to minimize requests
- **Polite User-Agent** header identifying the project
- **No authentication bypass** — only public data
For real-time FIX feeds, contact BRVM directly: [brvm.org/real-time-data-feed](https://www.brvm.org/en/real-time-data-feed)
## Contributing
PRs welcome! Priority areas:
1. Additional data sources (eodhd.com, Rich Bourse)
2. Historical data support
3. Tests (pytest + VCR cassettes for scraper tests)
4. TypeScript port for Node.js MCP hosts
## License
MIT
---
Built with ☕ in Mauritius by [Dilane Fogué Kamga](https://www.linkedin.com/in/dilane-fogue-kamga/) — Senior Software & AI Engineer, Financial Engineering MSc ([WorldQuant University](https://www.wqu.edu/mscfe)).
*Bridging AI and African capital markets.*
