tepilora-mcp 0.4.0

MCP server for Tepilora financial API

Tepilora MCP Server

MCP (Model Context Protocol) server for the 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

pip install tepilora-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

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

Claude Code

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

Run Directly

export TEPILORA_API_KEY=your-api-key
tepilora-mcp

Available Tools

Discovery (4 tools)

Tool	Description
list_namespaces	List all 26 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 244 operations

Curated (14 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
get_realtime_quotes	Realtime quotes for a market category
get_realtime_quote	Single realtime quote by symbol or TepiloraCode
get_realtime_chart	Intraday chart data (1D, 5D, 1M, 1Y)
get_realtime_calendar	Economic calendar with actual vs forecast
get_realtime_health	Data source health status

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 244 operations as individual tools (222 additional tools on top of the 22 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 244 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:

{
  "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

26 namespaces, 244 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 >= 0.3.2
• fastmcp >= 2.14, < 3

License

MIT