# DataBursatil MCP Server

MCP server to access the [DataBursatil](https://databursatil.com) API, which provides data from the Mexican stock market (BMV, BIVA).

## Requirements

- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- DataBursatil API token (get one at [databursatil.com](https://databursatil.com))

## Installation

### With uv (recommended)

```bash
# Clone or download the project
cd databursatil-mcp

# Install dependencies
uv sync
```

### With pip

```bash
cd databursatil-mcp
pip install -e .
```

## Configuration

The server requires a DataBursatil authentication token. Configure the `DATABURSATIL_TOKEN` environment variable:

```bash
# Linux/macOS
export DATABURSATIL_TOKEN="your_30_character_token"

# Windows (PowerShell)
$env:DATABURSATIL_TOKEN = "your_30_character_token"

# Windows (CMD)
set DATABURSATIL_TOKEN=your_30_character_token
```

### Configuration in Claude

Add the following configuration to your `claude_desktop_config.json` file:




### Configuration in Claude Code

```json
{
  "mcpServers": {
    "databursatil": {
      "command": "uv",
      "args": ["--directory", "/path/to/databursatil-mcp", "run", "databursatil-mcp"],
      "env": {
        "DATABURSATIL_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Available Tools

### 1. `get_emisoras`
Gets general information about issuers and their series.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `letra` | string | No | Filter by initial letter or word |
| `mercado` | string | No | "local", "global" or both |

**Usage example:**
```
"Show me issuers starting with A"
"List all issuers in the global market"
```

### 2. `get_intradia`
Gets intraday quotes during trading hours.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emisora_serie` | string | Yes | Up to 10 issuers. Ex: "AMXL*,FEMSAUBD" |
| `bolsa` | string | Yes | "BMV" or "BIVA" |
| `intervalo` | string | Yes | "1m", "5m" or "1h" |
| `inicio` | string | Yes | Date YYYY-MM-DD |
| `final` | string | Yes | Date YYYY-MM-DD |

**Usage example:**
```
"Show me intraday prices for AMXL* in 5-minute intervals for today"
```

### 3. `get_cotizaciones`
Gets current prices of issuers.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emisora_serie` | string | Yes | Up to 50 issuers |
| `concepto` | string | Yes | u,p,a,x,n,c,m,v,o,i (see table below) |
| `bolsa` | string | Yes | "BMV", "BIVA" or both |

**Available concepts:**
| Code | Description |
|------|-------------|
| u | Last price |
| p | Weighted average price |
| a | Previous price |
| x | Maximum price |
| n | Minimum price |
| c | Percentage change |
| m | Change in pesos |
| v | Volume |
| o | Operations |
| i | Accumulated amount |

**Usage example:**
```
"What is the current price of AMXL* and FEMSAUBD?"
"Show me the volume and percentage change for GFNORTEO"
```

### 4. `get_top`
Gets ranking of issuers by different criteria.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `variables` | string | Yes | "suben", "bajan", "importe", "volumen", "operaciones" |
| `bolsa` | string | Yes | "BMV" or "BIVA" (only one) |
| `cantidad` | int | Yes | 1-50 |
| `mercado` | string | Yes | "local" or "global" |
| `inicio` | string | Yes | Date YYYY-MM-DD |
| `final` | string | Yes | Date YYYY-MM-DD |

**Usage example:**
```
"What are the top 10 stocks gaining today on the BMV?"
"Top 5 issuers with highest volume this week"
```

### 5. `get_historicos`
Gets historical closing prices.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emisora_serie` | string | Yes | Single issuer |
| `inicio` | string | Yes | Date YYYY-MM-DD |
| `final` | string | Yes | Date YYYY-MM-DD |

**Usage example:**
```
"Show me the price history for AMXL* for the last month"
"BIMBOA closing prices for 2024"
```

### 6. `get_financieros`
Gets financial statements of issuers.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emisora` | string | Yes | Ticker WITHOUT series. Ex: "AMXL" |
| `periodo` | string | Yes | Format "1T_2025" (quarter_year) |
| `financieros` | string | Yes | "posicion", "flujos", "resultado_trimestre", "resultado_acumulado" |

**Usage example:**
```
"Show me FEMSA's balance sheet for Q1 2025"
"AMXL quarterly results for Q4 2024"
```

### 7. `get_indices`
Gets stock market index prices.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ticker` | string | No | Filter by index. Ex: "IPC", "DJI" |

**Usage example:**
```
"How is the IPC today?"
"Show me all stock market indices"
```

### 8. `get_tasas`
Gets Mexican money market rates.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ticker` | string | No | Filter by rate. Ex: "TIIE28" |

**Usage example:**
```
"What is the 28-day TIIE rate?"
"Show all reference rates"
```

### 9. `get_divisas`
Gets currency exchange rates.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ticker` | string | No | Currency pair. Ex: "USDMXN" |

**Usage example:**
```
"What's the dollar exchange rate?"
"Euro to peso exchange rate"
```

### 10. `get_commodities`
Gets commodity prices.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ticker` | string | No | Commodity. Ex: "WTI", "GOLD" |

**Usage example:**
```
"WTI oil price"
"How is gold doing today?"
```

### 11. `get_noticias`
Gets business and economy news.

No required parameters.

**Usage example:**
```
"What are the latest financial news?"
```

### 12. `get_cables`
Gets news wires from Mexican issuers.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `categorias` | string | No | "boletines", "top", "valuaciones", "flash", "generales" |

**Usage example:**
```
"Show me today's issuer bulletins"
"Market flash news"
```

### 13. `get_descargas`
Downloads end-of-day facts or valuations.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `archivo` | string | Yes | "hechos" or "guber" |
| `fecha` | string | Yes | Date YYYY-MM-DD (business days) |

**Usage example:**
```
"Download last Friday's facts"
"Government valuations for January 15"
```

### 14. `get_hechos`
Gets filtered individual operations.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `emisora_serie` | string | Yes | Up to 10 issuers |
| `fecha` | string | Yes | Date YYYY-MM-DD |
| `horai` | string | Yes | Start time HH:MM |
| `horaf` | string | Yes | End time HH:MM |

**Usage example:**
```
"Show me AMXL* operations for today between 9:00 and 11:00"
```

### 15. `get_creditos`
Shows available credits for the token.

No required parameters.

**Usage example:**
```
"How many credits do I have left?"
```

## Development

### Test the server locally

```bash
# With MCP inspector
uv run mcp dev src/databursatil_mcp/server.py

# Run directly
uv run databursatil-mcp
```


## Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| "Token not configured" | Environment variable not set | Configure `DATABURSATIL_TOKEN` |
| "Invalid or expired token" | Incorrect token | Verify your token at databursatil.com |
| "Credits exhausted" | No credits available | Wait until the 1st of the month |
| "Invalid parameters" | Incorrect format | Check date and parameter format |

## License

MIT

## Links

- [DataBursatil](https://databursatil.com)
- [API Documentation](https://databursatil.com/docs.html)