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:

# Example configuration object (before base64 encoding):
{
  "username": "your-xbrl-username",
  "password": "your-xbrl-password",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Installation & Setup

Prerequisites

Python 3.13+
XBRL-US API account and credentials
uv (for dependency management)

Local Development

Clone the repository:

git clone <repository-url>
cd xbrl-us-mcp

Install dependencies:

uv sync

Run the server:

uv run playground

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

Usage Example

Search for Companies in 2023

Tool: search_companies
Parameters: {"year": 2023, "limit": 10}

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

xbrl-us-mcp/
├── src/
│   ├── index.py              # Main FastMCP server
│   └── funcs/
│       ├── __init__.py
│       └── middleware.py     # Session authentication middleware
├── smithery.yaml             # Deployment configuration
├── pyproject.toml           # Python dependencies
└── README.md               # This file

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:

New XBRL instance created for session abc123...: token...

Subsequent Requests in Same Session:

Reusing valid XBRL session for abc123...
Reusing XBRL instance: token...

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

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

This project is licensed under the MIT License.

xbrl-us-mcp