XBRL-US MCP Server

A Model Context Protocol (MCP) server that provides secure access to XBRL-US financial data with session-based authentication and state persistence.

Features

• Session-Based Authentication: Efficient session management with automatic token reuse

• State Persistence: XBRL instances persist across multiple tool calls within the same session

• Company Search: Search for companies by fiscal year and retrieve financial facts

• Secure Credentials: SHA256-hashed credential validation and secure storage

Tools Available

Search Companies

Search for companies by fiscal year and retrieve financial facts.

• Parameters:

  • year (integer): Fiscal year to search for

  • limit (optional, default: 10): Maximum number of results to return

• Returns: List of financial facts for companies in the specified year

Authentication

This server requires XBRL-US API credentials provided via URL parameters:

• Username: Your XBRL-US account username

• Password: Your XBRL-US account password

• Client ID: Your XBRL-US API client ID

• Client Secret: Your XBRL-US API client secret

Configuration Format

Credentials are passed as a base64-encoded JSON object in the config URL parameter:

Installation & Setup

Prerequisites

• Python 3.13+

• XBRL-US API account and credentials

• uv (for dependency management)

Local Development

1. Clone the repository:

2. Install dependencies:

3. Run the server:

The server will start on port 8081 by default and open smithery.ai playground

Usage Example

Search for Companies in 2023

This will return financial facts for companies with data available for fiscal year 2023.

Architecture

Session Management

The server implements sophisticated session management:

• FastMCP Session IDs: Uses FastMCP's built-in session identification

• Session-Scoped Storage: XBRL instances persist across requests within the same session

• Automatic Token Reuse: Reuses valid XBRL authentication tokens to improve performance

• Credential Validation: SHA256 hashing ensures secure credential comparison

• Token Expiration: Automatically handles expired tokens and re-authenticates when needed

Project Structure

Session Persistence Benefits

• Performance: Eliminates redundant authentication calls

• Efficiency: Reuses XBRL instances across multiple tool calls

• Reliability: Handles token expiration gracefully

• Security: Secure credential hashing and validation

Expected Behavior

First Request in Session:

Subsequent Requests in Same Session:

Error Handling

The server provides detailed error messages for:

• Missing or invalid credentials

• Authentication failures

• Token expiration

• Network connectivity issues

• Invalid search parameters

Security Features

• Credential Hashing: SHA256 hashing of credentials for secure comparison

• Session Isolation: Each session maintains independent authentication state

• Token Validation: Automatic validation of XBRL token expiration

• Secure Storage: Credentials are never stored in plain text

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

License

This project is licensed under the MIT License.