https://github.com/danilobatson/lunarcrush-mcp-sdk
Lightweight SDK for connecting LLMs to LunarCrush social crypto data via Model Context Protocol (MCP)
https://github.com/danilobatson/lunarcrush-mcp-sdk
ai artificial-intelligence bitcoin blockchain crypto crypto-api cryptocurrency llm lunarcrush mcp model-context-protocol nodejs sentiment-analysis social-data trading typescript
Last synced: 3 months ago
JSON representation
Lightweight SDK for connecting LLMs to LunarCrush social crypto data via Model Context Protocol (MCP)
- Host: GitHub
- URL: https://github.com/danilobatson/lunarcrush-mcp-sdk
- Owner: danilobatson
- License: mit
- Created: 2025-09-11T04:03:07.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-11T04:39:40.000Z (11 months ago)
- Last Synced: 2025-10-06T19:53:10.627Z (10 months ago)
- Topics: ai, artificial-intelligence, bitcoin, blockchain, crypto, crypto-api, cryptocurrency, llm, lunarcrush, mcp, model-context-protocol, nodejs, sentiment-analysis, social-data, trading, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@jamaalbuilds/lunarcrush-mcp
- Size: 15.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🌙 LunarCrush MCP SDK
[](https://badge.fury.io/js/%40jamaalbuilds%2Flunarcrush-mcp)
[](https://opensource.org/licenses/MIT)
Lightweight, LLM-agnostic SDK for connecting any LLM to LunarCrush social crypto data via Model Context Protocol (MCP).
## 🚀 Features
- **Zero Configuration** - Just your API key and you're ready
- **100% Dynamic** - Auto-discovers tools, future-proof against changes
- **LLM Agnostic** - Raw schemas, you format for your LLM choice
- **Lightweight** - Minimal dependencies, zero maintenance needed
- **TypeScript Ready** - Full type safety and IntelliSense support
## 📦 Installation
```bash
npm install @jamaalbuilds/lunarcrush-mcp @modelcontextprotocol/sdk
```
## 🔑 Quick Start
```typescript
import LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';
// 1. Connect (one time setup)
const mcp = new LunarCrushMCP('your-api-key');
await mcp.connect();
// 2. Get tools for your LLM
const tools = mcp.getToolsWithDetails();
// Raw schemas - you format for your LLM
// 3. LLM calls tools through SDK
const result = await mcp.callTool('Topic', { topic: 'bitcoin' });
// 4. Clean up when done
await mcp.disconnect();
```
## 🤖 LLM Integration Examples
### OpenAI Function Calling
```typescript
import OpenAI from 'openai';
import LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);
await mcp.connect();
// Format tools for OpenAI (you control the formatting)
const tools = mcp.getToolsWithDetails();
const functions = tools.map(tool => ({
name: tool.name,
description: tool.description,
parameters: tool.schema
}));
const response = await openai.chat.completions.create({
model: 'gpt-4',
messages: [{ role: 'user', content: 'What is Bitcoin trending at?' }],
functions,
function_call: 'auto'
});
// Execute function call
if (response.choices[0].message.function_call) {
const { name, arguments: args } = response.choices[0].message.function_call;
const result = await mcp.executeFunction(name, args);
console.log('Bitcoin data:', result);
}
```
### Anthropic Tool Use
```typescript
import Anthropic from '@anthropic-ai/sdk';
import LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);
await mcp.connect();
// Format tools for Anthropic (you control the formatting)
const toolsData = mcp.getToolsWithDetails();
const tools = toolsData.map(tool => ({
name: tool.name,
description: tool.description,
input_schema: tool.schema
}));
const response = await anthropic.messages.create({
model: 'claude-3-sonnet-20240229',
max_tokens: 1000,
messages: [{ role: 'user', content: 'Analyze Bitcoin social sentiment' }],
tools
});
// Execute tool calls
for (const content of response.content) {
if (content.type === 'tool_use') {
const result = await mcp.callTool(content.name, content.input);
console.log('Analysis result:', result);
}
}
```
### Google Gemini Integration
```typescript
import { GoogleGenerativeAI } from '@google/generative-ai';
import LunarCrushMCP from '@jamaalbuilds/lunarcrush-mcp';
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const mcp = new LunarCrushMCP(process.env.LUNARCRUSH_API_KEY);
await mcp.connect();
// Get detailed tool information for better LLM understanding
const toolsData = mcp.getToolsWithDetails();
const prompt = `You are a crypto analyst with access to LunarCrush tools.
AVAILABLE TOOLS:
${toolsData.map(tool => {
const { name, description, parameterInfo } = tool;
return `${name}: ${description}
Required parameters: ${parameterInfo.required.join(', ') || 'none'}
Optional parameters: ${parameterInfo.optional.join(', ') || 'none'}
Parameter types: ${JSON.stringify(parameterInfo.types)}
Enum values: ${JSON.stringify(parameterInfo.enums)}`;
}).join('\n\n')}
Task: Analyze Bitcoin's current performance and social sentiment.
Choose appropriate tools with EXACT parameter formatting.
CRITICAL:
- Use arrays for array parameters: ["item1", "item2"]
- Use exact enum values from the options provided
- Follow parameter types precisely
Respond with JSON:
{
"selected_tools": [
{
"name": "exact_tool_name",
"arguments": {exact_arguments_with_proper_types},
"reasoning": "why you chose this tool"
}
]
}`;
const model = genAI.getGenerativeModel({ model: 'gemini-2.0-flash-lite' });
const result = await model.generateContent(prompt);
// Parse and execute chosen tools
const response = JSON.parse(result.response.text());
for (const choice of response.selected_tools) {
const toolResult = await mcp.callTool(choice.name, choice.arguments);
console.log(`${choice.name} result:`, toolResult);
}
```
## 📋 Available Methods
### Connection Management
```typescript
const mcp = new LunarCrushMCP(apiKey);
await mcp.connect(); // Connect to MCP server
await mcp.disconnect(); // Clean disconnect
const status = mcp.getStatus(); // Get connection status
```
### Tool Discovery
```typescript
const tools = mcp.getTools(); // Get basic tools with schemas
const detailedTools = mcp.getToolsWithDetails(); // Get enhanced tool info for LLMs
const tool = mcp.getTool('Topic'); // Get specific tool schema
await mcp.refreshTools(); // Refresh tool list (if MCP updates)
```
### Tool Execution
```typescript
// Single tool call
const result = await mcp.callTool('Topic', { topic: 'bitcoin' });
// Execute LLM function call
const result = await mcp.executeFunction(name, args);
// Batch multiple tool calls
const results = await mcp.callTools([
{ name: 'Topic', args: { topic: 'bitcoin' } },
{ name: 'Cryptocurrencies', args: { sort: 'galaxy_score', limit: 10 } }
]);
```
## 🛠 Available Tools
The SDK dynamically discovers all available tools from the LunarCrush MCP server. Common tools include:
- **Topic** - Get detailed crypto/stock data and social metrics
- **Cryptocurrencies** - List and sort cryptocurrencies by various metrics
- **Topic_Time_Series** - Historical data and trends
- **Topic_Posts** - Recent social posts and engagement
- **Search** - Search across all topics and social data
- **Creator** - Social media creator analysis
- **And more...** (auto-discovered)
## 📝 Enhanced Tool Information
The `getToolsWithDetails()` method provides LLM-friendly tool information:
```typescript
const toolsData = mcp.getToolsWithDetails();
console.log(toolsData[0]);
/*
{
name: "Topic_Time_Series",
description: "Get historical time series metrics...",
schema: {
type: "object",
properties: { ... },
required: ["topic"]
},
parameterInfo: {
required: ["topic"],
optional: ["metrics", "interval"],
types: {
topic: "string",
metrics: "array",
interval: "enum"
},
enums: {
interval: ["1d", "1w", "1m", "3m", "6m", "1y", "all"]
}
}
}
*/
```
This enhanced information helps LLMs understand:
- Which parameters are required vs optional
- Exact parameter types (string, array, enum, etc.)
- Valid enum values for better accuracy
## 🔒 Error Handling
The SDK passes through all MCP server errors with detailed validation messages:
```typescript
try {
const result = await mcp.callTool('Topic_Time_Series', {
topic: 'bitcoin',
metrics: 'price,volume', // ❌ Should be array: ['price', 'volume']
interval: 'day' // ❌ Should be '1d', not 'day'
});
} catch (error) {
console.error('MCP validation error:', error.message);
// Error shows exactly what's wrong with parameters
}
```
## 📝 TypeScript Support
Full TypeScript support with proper types:
```typescript
import LunarCrushMCP, { MCPTool, MCPToolResult } from '@jamaalbuilds/lunarcrush-mcp';
const mcp: LunarCrushMCP = new LunarCrushMCP(apiKey);
const tools: MCPTool[] = mcp.getTools();
const result: MCPToolResult = await mcp.callTool('Topic', { topic: 'bitcoin' });
```
## 🎯 Design Philosophy
This SDK is intentionally minimal and LLM-agnostic:
- **No LLM-specific formatting** - You control how to format schemas for your LLM
- **No maintenance burden** - SDK just passes through what MCP provides
- **Future-proof** - Works with any current or future LLM provider
- **Zero assumptions** - Doesn't assume we know how LLMs will evolve
## 🚀 Get Started
1. **Get LunarCrush API Key**: [lunarcrush.com/developers/api](https://lunarcrush.com/developers/api)
2. **Install the SDK**: `npm install @jamaalbuilds/lunarcrush-mcp`
3. **Format tools for your LLM**: Use examples above for your LLM provider
4. **Start analyzing**: Your LLM now has access to real-time crypto social data!
## 📖 Documentation
- [LunarCrush API Docs](https://lunarcrush.com/developers/api)
- [Model Context Protocol](https://modelcontextprotocol.io)
## 💬 Support
- [GitHub Issues](https://github.com/danilobatson/lunarcrush-mcp-sdk/issues)
- [Portfolio](https://danilobatson.github.io/)
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---
**Built by [Danilo Jamaal](https://danilobatson.github.io/) for the LunarCrush community**