tepilora-mcp 0.1.6
MCP server for Tepilora financial API
Requires Python: >=3.10
Keywords: tepilora, mcp, finance, api, llm, claude

# Tepilora MCP Server

[![PyPI](https://img.shields.io/pypi/v/tepilora-mcp)](https://pypi.org/project/tepilora-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/tepilora-mcp)](https://pypi.org/project/tepilora-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

MCP (Model Context Protocol) server for the [Tepilora](https://pypi.org/project/Tepilora/) financial API.

Gives AI assistants (Claude, Codex, etc.) native access to **226 financial data operations** — securities search, portfolio analytics, news, bonds, and more.

## Features

- **16 curated tools** in default mode, **234 tools** in full mode
- **Async client** (`AsyncTepiloraClient`) — non-blocking, optimized for MCP
- **Smart caching** — TTL + LRU eviction, skips mutating operations
- **Credit tracking** — per-session usage limits with configurable caps
- **Error handling** — user-friendly messages instead of raw tracebacks
- **Arrow IPC streaming** — binary format for large result sets

## Install

```bash
pip install tepilora-mcp
```

## Quick Start

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tepilora": {
      "command": "tepilora-mcp",
      "env": {
        "TEPILORA_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add tepilora tepilora-mcp -e TEPILORA_API_KEY=your-api-key
```

### Run Directly

```bash
export TEPILORA_API_KEY=your-api-key
tepilora-mcp
```

## Available Tools

### Discovery (4 tools)

| Tool | Description |
|------|-------------|
| `list_namespaces` | List all 24 API namespaces with operation counts |
| `list_operations` | List operations for a namespace |
| `describe_operation` | Get parameter details for any operation |
| `call_operation` | Execute any of the 226 operations |

### Curated (9 tools)

| Tool | Description |
|------|-------------|
| `search_securities` | Search stocks, ETFs, bonds, funds |
| `get_security_details` | Get security information |
| `get_price_history` | Historical price data |
| `create_portfolio` | Create a portfolio |
| `get_portfolio_returns` | Portfolio return analysis |
| `run_analytics` | 68 analytics functions (summary-first: preview + MCP resource for full data) |
| `search_news` | Search financial news |
| `screen_bonds` | Screen bonds by criteria |
| `get_yield_curve` | Yield curve data |

### Utility (3 tools)

| Tool | Description |
|------|-------------|
| `clear_cache` | Clear the in-memory result cache |
| `get_credit_usage` | View session credit usage and limits |
| `reset_credits` | Reset the session credit counter |

### Streaming (1 tool)

| Tool | Description |
|------|-------------|
| `call_operation_arrow_stream` | Call any operation in Arrow IPC binary format |

### Full Mode (opt-in)

Set `TEPILORA_MCP_FULL_TOOLS=true` to expose all 226 operations as individual tools (218 additional tools on top of the 16 default).

## Configuration

| Environment Variable | Required | Default | Description |
|---------------------|----------|---------|-------------|
| `TEPILORA_API_KEY` | Yes | - | Your Tepilora API key |
| `TEPILORA_BASE_URL` | No | `https://tepiloradata.com` | API base URL |
| `TEPILORA_FALLBACK_URL` | No | `http://49.13.34.1` | Fallback API URL (used if base URL returns HTML) |
| `TEPILORA_MCP_FULL_TOOLS` | No | `false` | Register all 226 operations as tools |
| `TEPILORA_MCP_TIMEOUT` | No | `30` | Request timeout in seconds |
| `TEPILORA_MCP_CACHE_TTL` | No | `300` | Cache TTL in seconds (`0` disables cache) |
| `TEPILORA_MCP_CACHE_MAX_SIZE` | No | `1000` | Max cached entries (LRU eviction) |
| `TEPILORA_MCP_CREDIT_LIMIT` | No | `0` | Session credit cap (`0` = unlimited) |

## Caching

Results are cached in memory with a configurable TTL (default 5 minutes). Mutating operations (`create`, `update`, `delete`, `run`, etc.) are never cached. Use the `clear_cache` tool to manually flush.

## Credit Tracking

Each API operation has a credit cost (defined in the SDK schema). Set `TEPILORA_MCP_CREDIT_LIMIT` to cap per-session usage. Use `get_credit_usage` to monitor and `reset_credits` to start fresh.

## Error Handling

All tools return structured error messages instead of raw exceptions:

```json
{
  "error": "Rate limit reached: wait and retry, or reduce request frequency.",
  "details": "HTTPStatusError: 429 Too Many Requests"
}
```

Handled errors: HTTP 401/403/404/429/5xx, timeouts, connection failures, SDK errors, invalid parameters.

## API Coverage

24 namespaces, 226 operations:

| Namespace | Ops | Examples |
|-----------|-----|---------|
| securities | 12 | search, filter, history, facets |
| portfolio | 19 | create, returns, attribution, optimize |
| analytics | 68 | rolling volatility, Sharpe, drawdown, VaR |
| news | 7 | search, latest, trending |
| bonds | 7 | analyze, screen, curve, spread |
| stocks | 9 | technicals, screening, peers |
| options | 6 | pricing, Greeks, IV |
| macro | 6 | economic indicators, calendar |
| esg | 5 | scores, screening |
| *+ 15 more* | | alerts, audit, billing, clients, documents, ... |

## Requirements

- Python 3.10+
- [`Tepilora`](https://pypi.org/project/Tepilora/) >= 0.3.2
- [`fastmcp`](https://pypi.org/project/fastmcp/) >= 2.14, < 3

## License

MIT