npm package: @orbt-finance/mcp-server
Description: Advanced AI-powered MCP server for ORBT Financial Intelligence API with Gemini-powered natural language credit analysis, multi-company comparisons, Bitcoin scenario modeling, and comprehensive sector risk assessment
Author: ORBT Technologies
Latest version: 3.3.0

# ORBT MCP Server

Advanced MCP (Model Context Protocol) server for ORBT Financial Intelligence API, featuring AI-powered credit rating analysis with Bitcoin treasury insights.

**Version: 3.3.0** | **Methodology: v0.2.2** - Bitcoin-aware credit ratings where BTC holdings improve creditworthiness

## Features

### 🎯 Direct Rating Lookup (`orbt_rating`)
- Fetch real-time credit ratings for 10,000+ securities
- Support for ticker symbols and CUSIP identifiers
- Automatic typo correction and validation
- Bitcoin treasury impact analysis
- Sector comparisons and peer benchmarking

### 🤖 AI Analyst (`orbt_analyst`)
Powered by Gemini AI, offering 6 core capabilities:

1. **Single Company Analysis** - Deep dive into any company's credit profile
2. **Multi-Company Comparisons** - Side-by-side analysis of up to 10 companies
3. **Bitcoin Scenario Modeling** - What-if analysis for BTC price movements
4. **Sector/Industry Analysis** - Comprehensive sector risk assessments
5. **Historical Trend Analysis** - 5-year trends with charts and timelines
6. **Explanatory Intelligence** - Understand rating methodologies and factors

## Installation

### NPM Global Installation
```bash
npm install -g @orbt-finance/mcp-server
```

### Configuration

#### Option 1: API Key (Recommended)
Set your ORBT API key as an environment variable:
```bash
export ORBT_API_KEY=your_api_key_here
```

Get your API key at https://orbt.finance

#### Option 2: Lightning Pay-Per-Query
No API key needed - pay 99 sats per query via Lightning Network

## Setup for Claude Desktop

Add to your Claude configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "orbt": {
      "command": "npx",
      "args": ["@orbt-finance/mcp-server"],
      "env": {
        "ORBT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage Examples

### 1️⃣ Single Company Rating

**Basic Lookup:**
```
Tool: orbt_rating
Input: { "identifier": "AAPL" }

Response: {
  "rating": {
    "ticker": "AAPL",
    "company": "Apple Inc.",
    "rating": "AA+",
    "outlook": "Stable",
    "bitcoin_holdings": 0,
    "bitcoin_impact": "Neutral"
  }
}
```

**CUSIP Lookup:**
```
Tool: orbt_rating
Input: { "identifier": "037833100" }  // Apple's CUSIP
```

### 2️⃣ Multi-Company Comparison

**Compare Tech Giants:**
```
Tool: orbt_analyst
Input: { "query": "Compare the credit profiles of AAPL, MSFT, GOOGL, and AMZN" }

Response: Detailed comparison table showing:
- Credit ratings (AA+ to AAA range)
- Financial metrics (debt/equity, interest coverage)
- Bitcoin holdings and impact
- Relative strengths and weaknesses
- Investment recommendations
```

**Bitcoin Treasury Leaders:**
```
Tool: orbt_analyst
Input: { "query": "Compare MSTR vs TSLA vs COIN credit ratings and Bitcoin strategies" }
```

### 3️⃣ Bitcoin Scenario Analysis

**Price Impact Scenarios:**
```
Tool: orbt_analyst
Input: { "query": "What happens to MicroStrategy's rating if Bitcoin reaches $200,000?" }

Response: 
- Current rating: AAA (with BTC at $100k)
- Projected rating at $200k: AAA (maintained)
- Bitcoin treasury value: $130B+
- Debt coverage improvement: 300%+
- Risk analysis and recommendations
```

**Sector-Wide Impact:**
```
Tool: orbt_analyst
Input: { "query": "How would Bitcoin at $50k affect tech sector credit ratings?" }
```

**Corporate Treasury Analysis:**
```
Tool: orbt_analyst
Input: { "query": "What if Apple bought 100,000 Bitcoin?" }
```

### 4️⃣ Sector/Industry Analysis

**Banking Sector Risk:**
```
Tool: orbt_analyst
Input: { "query": "Analyze credit risk in the banking sector" }

Response: 
- Sector average rating: A+
- Top performers: JPM (AA), BAC (A+)
- Risk factors: Interest rate exposure, loan defaults
- Bitcoin adoption: Limited (regulatory constraints)
- Outlook and recommendations
```

**Industry Comparisons:**
```
Tool: orbt_analyst
Input: { "query": "Compare tech sector vs financial sector credit profiles" }
```

**S&P 500 Analysis:**
```
Tool: orbt_analyst
Input: { "query": "Which S&P 500 sectors have the best credit ratings?" }
```

### 5️⃣ Historical Trend Analysis

**5-Year Company History:**
```
Tool: orbt_analyst
Input: { "query": "Show me Tesla's credit rating trend over the past 5 years" }

Response:
- 2020: BBB+ (pre-Bitcoin)
- 2021: A- (Bitcoin purchase)
- 2022: A (despite market downturn)
- 2023: A+ (profitability surge)
- 2024: AA (current)
- Key events and catalysts
- Correlation with BTC price
```

**Rating Migration Analysis:**
```
Tool: orbt_analyst
Input: { "query": "Track MicroStrategy's rating changes since adopting Bitcoin" }
```

**Market Correlation:**
```
Tool: orbt_analyst
Input: { "query": "How have credit ratings correlated with Bitcoin price over time?" }
```

### 6️⃣ Explanatory Intelligence

**Methodology Explanation:**
```
Tool: orbt_analyst
Input: { "query": "Explain why MicroStrategy has an AAA rating despite high debt" }

Response:
- Bitcoin treasury value: $60B+
- Debt obligations: $6B
- Coverage ratio: 10x
- Methodology factors:
  * Bitcoin treated as Tier 1 asset
  * Mark-to-market valuation
  * Volatility adjustments
  * Scenario stress testing
```

**Rating Factor Analysis:**
```
Tool: orbt_analyst
Input: { "query": "What factors determine a company's credit rating in your methodology?" }
```

**Bitcoin Impact Explanation:**
```
Tool: orbt_analyst
Input: { "query": "How do Bitcoin holdings improve credit ratings?" }
```

## Advanced Queries

### Portfolio Optimization
```
"Which companies should I add to improve my portfolio's credit quality?"
"Suggest 5 companies with improving credit trends"
"Find undervalued companies with strong credit ratings"
```

### Risk Assessment
```
"What are the biggest credit risks in the market right now?"
"Which companies are most vulnerable to a Bitcoin crash?"
"Analyze concentration risk in tech sector debt"
```

### Predictive Analysis
```
"Predict rating changes for the next quarter"
"Which companies are likely to be upgraded?"
"What would trigger a downgrade for Apple?"
```

## Error Handling

### Common Issues and Solutions

**Invalid Ticker:**
```
Input: { "identifier": "APPL" }  // Typo
Response: Automatically corrects to "AAPL" with notice
```

**Missing Data:**
```
Input: { "identifier": "PRIVATE_CO" }
Response: {
  "error": "No data available",
  "suggestions": [
    "Check ticker on financial websites",
    "Try a public company instead",
    "Use S&P 500 constituents"
  ]
}
```

**Query Too Vague:**
```
Input: { "query": "ratings" }
Response: {
  "error": "Query too vague",
  "suggestions": [
    "Specify a company: 'What is Apple's rating?'",
    "Ask about sectors: 'Analyze tech sector ratings'",
    "Request comparisons: 'Compare MSFT and GOOGL'"
  ]
}
```

## Available Resources

Access these resources for additional data:

- `orbt://ratings` - Complete ratings database (10,000+ securities)
- `orbt://bitcoin-treasuries` - Corporate Bitcoin holdings tracker
- `orbt://market-data` - Real-time market intelligence

## Available Prompts

Pre-configured prompts for common analyses:

- `credit_analysis` - Comprehensive credit rating analysis with Bitcoin insights

## Environment Variables

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `ORBT_API_KEY` | No* | Your ORBT API key | - |
| `ORBT_API_URL` | No | API endpoint URL | https://orbt.finance |

*Required for unlimited queries. Without it, pay-per-query via Lightning (99 sats)

## Troubleshooting

### API Key Issues
```bash
# Verify API key is set
echo $ORBT_API_KEY

# Test the connection
npx @orbt-finance/mcp-server test
```

### Claude Desktop Not Finding Tools
1. Restart Claude Desktop after configuration
2. Check logs: `~/Library/Logs/Claude/`
3. Verify config file syntax (valid JSON)

### Lightning Payment Issues
- Ensure Lightning wallet is funded
- Invoice expires after 10 minutes
- Minimum channel capacity: 10,000 sats

### Rate Limiting
- Free tier: 100 requests/day
- Pro tier: 1,000 requests/day
- Enterprise: Unlimited

## Performance Tips

1. **Batch Comparisons**: Compare multiple companies in one query instead of individual lookups
2. **Use Specific Tickers**: More accurate than company names
3. **Cache Results**: Ratings update daily, cache for 24 hours
4. **Parallel Queries**: The analyst can handle complex multi-part questions

## Support

- **Documentation**: https://orbt.finance/docs/mcp
- **API Status**: https://status.orbt.finance
- **Email**: agents@orbt.finance
- **Discord**: https://discord.gg/orbt
- **GitHub Issues**: https://github.com/orbt-finance/mcp-server/issues

## License

MIT License - © 2024 ORBT Technologies

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and updates.

---

*Built with ❤️ for the Bitcoin and AI communities*