# Price Service MCP - Real Implementation Examples
This document provides actual test results and implementation examples for teams integrating the Price Service MCP server.
## 🚀 Quick Start
Run the test examples:
```bash
cd examples
node test-calls.js
```
## 📊 Real API Call Examples
### Example 1: Basic Bitcoin Price Request
**MCP Tool Call:**
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "BTC"
}
}
```
**Expected MCP Response Format:**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"type\": \"candlestick\",\n \"open\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"98745.21\"\n },\n \"close\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"99123.45\"\n },\n \"high\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"99876.54\"\n },\n \"low\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"98234.12\"\n },\n \"volume\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"8543.21456789\"\n },\n \"price\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"99123.45\"\n }\n}"
}
]
}
```
### Example 2: Historical Bitcoin Price (Actual Working Response)
**MCP Tool Call:**
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "BTC",
"timestampSEC": "1760225952",
"service": "coinbase"
}
}
```
**Actual MCP Response (From Live Test):**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"type\": \"candlestick\",\n \"open\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"112976.01\"\n },\n \"close\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"110768.89\"\n },\n \"high\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"113439.99\"\n },\n \"low\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"109683.96\"\n },\n \"volume\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"10041.88198008\"\n },\n \"price\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"110768.89\"\n }\n}"
}
]
}
```
### Example 3: Ethereum with Binance Exchange
**MCP Tool Call:**
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "ETH",
"service": "binance",
"toFiat": "USD"
}
}
```
**Expected MCP Response Format:**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"type\": \"candlestick\",\n \"open\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"3456.78\"\n },\n \"close\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"3523.91\"\n },\n \"high\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"3587.45\"\n },\n \"low\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"3423.12\"\n },\n \"volume\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"45632.87654321\"\n },\n \"price\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"3523.91\"\n }\n}"
}
]
}
```
### Example 4: Solana in EUR with 1h Resolution
**MCP Tool Call:**
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "SOL",
"service": "binance",
"resolution": "1h",
"toFiat": "EUR"
}
}
```
**Expected MCP Response Format:**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"type\": \"candlestick\",\n \"open\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"234.56\"\n },\n \"close\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"237.89\"\n },\n \"high\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"241.23\"\n },\n \"low\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"232.45\"\n },\n \"volume\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"12876.54321098\"\n },\n \"price\": {\n \"mathjs\": \"BigNumber\",\n \"value\": \"237.89\"\n }\n}"
}
]
}
```
### Example 5: Health Check
**MCP Tool Call:**
```json
{
"tool": "health_check",
"arguments": {}
}
```
**Healthy Service Response:**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"status\": \"healthy\",\n \"priceService\": {\n \"status\": \"healthy\"\n },\n \"timestamp\": \"2025-10-12T23:39:25.061Z\"\n}"
}
]
}
```
**Unhealthy Service Response (Actual from Test):**
```json
{
"content": [
{
"type": "text",
"text": "{\n \"status\": \"unhealthy\",\n \"error\": \"Request failed with status code 404\",\n \"timestamp\": \"2025-10-12T23:39:25.061Z\"\n}"
}
]
}
```
## 🎯 Integration Guide for Development Teams
### 1. Configure Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"price-service": {
"command": "node",
"args": ["/path/to/price-service-mcp/build/index.js"]
}
}
}
```
### 2. Available Tools
#### `get_price`
- **Required**: `fromSym` (string) - Cryptocurrency symbol
- **Optional**: `timestampSEC`, `service`, `resolution`, `toFiat`, `timezone`
- **Returns**: Candlestick data with OHLCV values as BigNumber objects
#### `health_check`
- **Parameters**: None
- **Returns**: Health status of MCP server and underlying price service
### 3. Error Handling
The MCP server provides graceful error handling:
```json
{
"content": [
{
"type": "text",
"text": "Error: [Descriptive error message]"
}
]
}
```
### 4. Data Format
All price data uses BigNumber format for precision:
```json
{
"mathjs": "BigNumber",
"value": "123456.789"
}
```
### 5. Supported Parameters
- **Exchanges**: `coinbase`, `binance`, `kraken`
- **Resolutions**: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`
- **Fiat Currencies**: `USD`, `EUR`, and others supported by the exchange
- **Timezones**: Standard timezone strings (default: `UTC`)
## 🔧 Testing Your Integration
1. **Start the MCP Server**:
```bash
npm run build
npm start
```
2. **Run Test Examples**:
```bash
cd examples
node test-calls.js
```
3. **Test in Claude Desktop**:
- Configure the MCP server in Claude Desktop
- Try simple commands like "Get the current Bitcoin price"
- Test with different parameters and cryptocurrencies
## 📝 Common Use Cases
### Portfolio Tracking
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "BTC",
"service": "coinbase"
}
}
```
### Historical Analysis
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "ETH",
"timestampSEC": "1697875200",
"resolution": "1h"
}
}
```
### Multi-Exchange Comparison
```json
{
"tool": "get_price",
"arguments": {
"fromSym": "SOL",
"service": "binance"
}
}
```
## 🐛 Troubleshooting
1. **500 Errors**: Usually indicate issues with the underlying price service
2. **404 Errors**: Health endpoint may not be available
3. **Connection Issues**: Check if the price service is accessible
4. **Invalid Symbols**: Verify cryptocurrency symbols are supported by the chosen exchange
## 📞 Support
For integration support or questions, refer to the main repository documentation or create an issue in the GitHub repository.
