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 forlimit(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.