{"_id":"@bramburn/batch-llm-mcp-server","_rev":"3-343529265473b918bbdc0d8a3af8a7bf","name":"@bramburn/batch-llm-mcp-server","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@bramburn/batch-llm-mcp-server","version":"1.0.0","keywords":["mcp","batch","llm","ai","openai","anthropic","gemini"],"author":{"name":"Batch LLM MCP Server"},"license":"MIT","_id":"@bramburn/batch-llm-mcp-server@1.0.0","maintainers":[{"name":"bramburn","email":"nitrogen@gmail.com"}],"homepage":"https://github.com/bramburn/batch-message-mcp#readme","bugs":{"url":"https://github.com/bramburn/batch-message-mcp/issues"},"bin":{"batch-llm-mcp":"index.js","batch-llm-mcp-server":"index.js"},"dist":{"shasum":"0a4eb916d9f5d0f490d73e6758889af51af40ebf","tarball":"https://registry.npmjs.org/@bramburn/batch-llm-mcp-server/-/batch-llm-mcp-server-1.0.0.tgz","fileCount":5,"integrity":"sha512-ZCqPrjU64rCJ9lf2ymd7+LXFDuH69gzeOmzpUM7+UU368TgaWecPDoHPq03WueylAgfxEaxQOd9pBX1XPwYhag==","signatures":[{"sig":"MEQCIHwPfxaCTBmTLyqTK38bciRt3jpOoK4HrQXUveUUIVZAAiBeTuar8jnoRDjZllaTOA9RjdG9PEMGtwTTgA2xZhpJUg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58621},"main":"index.js","type":"module","engines":{"node":">=16.0.0"},"gitHead":"2e92436702c576dbfbdaf78da6d372a3a6163767","scripts":{"test":"node test.js","start":"node index.js","version":"npm test","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","prepublishOnly":"npm test"},"_npmUser":{"name":"bramburn","email":"nitrogen@gmail.com"},"repository":{"url":"git+https://github.com/bramburn/batch-message-mcp.git","type":"git"},"_npmVersion":"8.3.1","description":"MCP server for batch processing LLM requests with multiple providers","directories":{},"_nodeVersion":"16.14.0","dependencies":{"axios":"^1.6.0","dotenv":"^16.3.1","sqlite3":"^5.1.6","fs-extra":"^11.1.1","@modelcontextprotocol/sdk":"^0.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/batch-llm-mcp-server_1.0.0_1756131013950_0.6223853275161793","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."},"1.1.0":{"name":"@bramburn/batch-llm-mcp-server","version":"1.1.0","keywords":["mcp","batch","llm","ai","openai","anthropic","gemini","mistral"],"author":{"name":"Batch LLM MCP Server"},"license":"MIT","_id":"@bramburn/batch-llm-mcp-server@1.1.0","maintainers":[{"name":"bramburn","email":"nitrogen@gmail.com"}],"homepage":"https://github.com/bramburn/batch-message-mcp#readme","bugs":{"url":"https://github.com/bramburn/batch-message-mcp/issues"},"bin":{"batch-llm-mcp":"index.js","batch-llm-mcp-server":"index.js"},"dist":{"shasum":"5f804b435e5af1092cafd304059b334f6fff2f88","tarball":"https://registry.npmjs.org/@bramburn/batch-llm-mcp-server/-/batch-llm-mcp-server-1.1.0.tgz","fileCount":5,"integrity":"sha512-529nPgWD8kgx3Uj55um1XQ1dbZb09eQnB8N8/SQqJ4Dy2k6Q5tCP9Zq/HLDBkyy+Gi+f6LKp7ai8PBtzFUE5UQ==","signatures":[{"sig":"MEQCIC6HzuAKMYYDqeu5jUNOUlHCOgFU0Ogyk854QvK9/xOmAiAe/2X9iJQdfPo8BWYoDmX1vBBbbCcFG2MwV4rCw1v/rg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66683},"main":"index.js","type":"module","engines":{"node":">=16.0.0"},"gitHead":"7f324286caf88774e8292f57188ed9f15451ffe9","scripts":{"test":"node test.js","start":"node index.js","version":"npm test","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","prepublishOnly":"npm test"},"_npmUser":{"name":"bramburn","email":"nitrogen@gmail.com"},"repository":{"url":"git+https://github.com/bramburn/batch-message-mcp.git","type":"git"},"_npmVersion":"8.3.1","description":"MCP server for batch processing LLM requests with multiple providers","directories":{},"_nodeVersion":"16.14.0","dependencies":{"axios":"^1.6.0","dotenv":"^16.3.1","sqlite3":"^5.1.6","fs-extra":"^11.1.1","@modelcontextprotocol/sdk":"^0.5.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/batch-llm-mcp-server_1.1.0_1756133950155_0.9756529294576848","host":"s3://npm-registry-packages-npm-production"},"deprecated":"Package no longer supported. Contact Support at https://www.npmjs.com/support for more info."}},"time":{"created":"2025-08-25T14:10:13.861Z","modified":"2026-03-29T14:37:50.166Z","1.0.0":"2025-08-25T14:10:14.154Z","1.1.0":"2025-08-25T14:59:10.358Z"},"bugs":{"url":"https://github.com/bramburn/batch-message-mcp/issues"},"author":{"name":"Batch LLM MCP Server"},"license":"MIT","homepage":"https://github.com/bramburn/batch-message-mcp#readme","keywords":["mcp","batch","llm","ai","openai","anthropic","gemini","mistral"],"repository":{"url":"git+https://github.com/bramburn/batch-message-mcp.git","type":"git"},"description":"MCP server for batch processing LLM requests with multiple providers","maintainers":[{"name":"bramburn","email":"nitrogen@gmail.com"}],"readme":"# Batch LLM MCP Server\n\nA Model Context Protocol (MCP) server that enables batch processing of LLM requests across multiple providers (OpenAI, Anthropic, Google Gemini, Mistral AI) with significant cost savings.\n\n## š Features\n\n- **Multi-Provider Support**: OpenAI, Anthropic, Google Gemini, Mistral AI\n- **Batch Processing**: Queue messages and process them in batches for up to 50% cost savings\n- **File Integration**: Add file content to messages with XML wrapping\n- **Message Management**: Add, edit, delete, and search queue messages\n- **Response Search**: Search through completed batch responses\n- **Line-by-Line Reading**: Read specific lines from messages\n- **String Replacement**: Edit message content with find/replace\n- **SQLite Storage**: Persistent storage with configurable location\n- **Environment Variables**: Full configuration via environment variables\n- **Import/Export**: Backup and restore messages in JSON/CSV format\n- **Enhanced UX**: Emoji-rich interface with clear status indicators\n\n## š¦ Installation\n\n### Prerequisites\n- Node.js 16+\n- npm or yarn\n\n### Quick Start\n\n#### Option A: NPX (Recommended)\n```bash\n# Run directly with npx (no installation needed)\nnpx @bramburn/batch-llm-mcp-server\n```\n\n#### Option B: Clone and Build\n```bash\n# Clone the repository\ngit clone https://github.com/bramburn/batch-message-mcp.git\ncd batch-message-mcp\n\n# Install dependencies\nnpm install\n\n# Optional: Copy and configure environment variables\ncp .env.example .env\n# Edit .env with your API keys and preferences\n\n# Start the MCP server\nnpm start\n```\n\n### Using with MCP Clients\n\nAdd to your MCP client configuration (e.g., Claude Desktop):\n\n#### Option A: NPX Configuration (Recommended)\n```json\n{\n \"mcpServers\": {\n \"batch-llm\": {\n \"command\": \"npx\",\n \"args\": [\"@bramburn/batch-llm-mcp-server\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-openai-api-key-here\",\n \"OPENAI_DEFAULT_MODEL\": \"gpt-4\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-your-anthropic-api-key-here\",\n \"ANTHROPIC_DEFAULT_MODEL\": \"claude-3-sonnet-20240229\",\n \"GEMINI_API_KEY\": \"your-gemini-api-key-here\",\n \"GEMINI_DEFAULT_MODEL\": \"gemini-pro\",\n \"MISTRAL_API_KEY\": \"your-mistral-api-key-here\",\n \"MISTRAL_DEFAULT_MODEL\": \"mistral-large-latest\",\n \"BATCH_LLM_DEFAULT_PROVIDER\": \"openai\"\n }\n }\n }\n}\n```\n\n#### Option B: Local Installation Configuration\n```json\n{\n \"mcpServers\": {\n \"batch-llm\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/batch-message-mcp/index.js\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-openai-api-key-here\",\n \"OPENAI_DEFAULT_MODEL\": \"gpt-4\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-your-anthropic-api-key-here\",\n \"ANTHROPIC_DEFAULT_MODEL\": \"claude-3-sonnet-20240229\",\n \"GEMINI_API_KEY\": \"your-gemini-api-key-here\",\n \"GEMINI_DEFAULT_MODEL\": \"gemini-pro\",\n \"MISTRAL_API_KEY\": \"your-mistral-api-key-here\",\n \"MISTRAL_DEFAULT_MODEL\": \"mistral-large-latest\",\n \"BATCH_LLM_DEFAULT_PROVIDER\": \"openai\"\n }\n }\n }\n}\n```\n\n#### Advanced Configuration with Custom Database Location\n```json\n{\n \"mcpServers\": {\n \"batch-llm\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/batch-message-mcp/index.js\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-openai-api-key-here\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-your-anthropic-api-key-here\",\n \"BATCH_LLM_DB_PATH\": \"/Users/yourname/Documents/batch-llm/database.db\",\n \"BATCH_LLM_CONFIG_PATH\": \"/Users/yourname/Documents/batch-llm/config.json\"\n }\n }\n }\n}\n```\n\n## āļø Configuration\n\n### Method 1: MCP Client Configuration (Recommended)\n\nThe best way to configure the server is directly in your MCP client configuration. This keeps all settings in one place and follows MCP best practices.\n\n**Available Environment Variables:**\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `OPENAI_API_KEY` | OpenAI API key | `sk-your-openai-key` |\n| `OPENAI_DEFAULT_MODEL` | Default OpenAI model | `gpt-4` |\n| `OPENAI_BASE_URL` | Custom OpenAI base URL | `https://api.openai.com/v1` |\n| `OPENAI_ORGANIZATION_ID` | OpenAI organization ID | `org-your-org-id` |\n| `ANTHROPIC_API_KEY` | Anthropic API key | `sk-ant-your-key` |\n| `ANTHROPIC_DEFAULT_MODEL` | Default Anthropic model | `claude-3-sonnet-20240229` |\n| `ANTHROPIC_BASE_URL` | Custom Anthropic base URL | `https://api.anthropic.com` |\n| `GEMINI_API_KEY` | Google Gemini API key | `your-gemini-key` |\n| `GEMINI_DEFAULT_MODEL` | Default Gemini model | `gemini-pro` |\n| `GEMINI_BASE_URL` | Custom Gemini base URL | `https://generativelanguage.googleapis.com/v1beta` |\n| `MISTRAL_API_KEY` | Mistral AI API key | `your-mistral-key` |\n| `MISTRAL_DEFAULT_MODEL` | Default Mistral model | `mistral-large-latest` |\n| `MISTRAL_BASE_URL` | Custom Mistral base URL | `https://api.mistral.ai/v1` |\n| `BATCH_LLM_DATA_DIR` | Custom data directory | `/path/to/data` |\n| `BATCH_LLM_DB_PATH` | Custom database path | `/path/to/database.db` |\n| `BATCH_LLM_CONFIG_PATH` | Custom config file path | `/path/to/config.json` |\n| `BATCH_LLM_DEFAULT_PROVIDER` | Default provider for new messages | `openai` |\n\n### Method 2: Local Environment File\n\nCreate a `.env` file in the project root (see `.env.example` for all options):\n\n```bash\n# Database Configuration\nBATCH_LLM_DATA_DIR=/path/to/your/data/directory\nBATCH_LLM_DB_PATH=/path/to/your/database.db\n\n# OpenAI Configuration\nOPENAI_API_KEY=sk-your-openai-api-key-here\nOPENAI_DEFAULT_MODEL=gpt-4\n\n# Anthropic Configuration\nANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here\nANTHROPIC_DEFAULT_MODEL=claude-3-sonnet-20240229\n```\n\n### Method 3: Runtime Configuration\n\nYou can also configure providers using the `configure_provider` tool:\n\n```bash\n# Configure OpenAI\nconfigure_provider --provider openai --api_key sk-your-key --default_model gpt-4\n\n# Configure Anthropic\nconfigure_provider --provider anthropic --api_key sk-ant-your-key --default_model claude-3-sonnet\n```\n\n## ļæ½ Quick Start Example\n\nHere's a complete example of setting up the server with Claude Desktop:\n\n1. **Edit Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"batch-llm\": {\n \"command\": \"node\",\n \"args\": [\"/Users/yourname/batch-message-mcp/index.js\"],\n \"env\": {\n \"OPENAI_API_KEY\": \"sk-your-actual-openai-key\",\n \"ANTHROPIC_API_KEY\": \"sk-ant-your-actual-anthropic-key\"\n }\n }\n }\n}\n```\n\n2. **Restart Claude Desktop**\n\n3. **Start using the tools** - Claude will now have access to all batch processing tools!\n\n## ļ潚 ļø Usage\n\n### Basic Workflow\n\n1. **Add messages to queue**:\n ```bash\n add_message_to_queue --content \"Analyze this data\" --provider openai --model gpt-4\n ```\n\n2. **Add files to messages**:\n ```bash\n add_file_to_message --message_id 1 --file_path ./data.csv --position beginning\n ```\n\n3. **Review your queue**:\n ```bash\n list_queue_messages --status pending\n ```\n\n4. **Process batch** (cost-effective):\n ```bash\n process_batch --provider openai\n ```\n\n5. **Check status and get results**:\n ```bash\n check_batch_status\n ```\n\n6. **Search responses**:\n ```bash\n search_responses --query \"analysis results\"\n ```\n\n### Advanced Features\n\n#### Import/Export Messages\n```bash\n# Export all messages to JSON\nexport_messages --format json --output_path ./backup.json\n\n# Import messages from file\nimport_messages --file_path ./messages.json --provider openai\n```\n\n#### Message Editing\n```bash\n# Edit message content\nedit_message_content --message_id 1 --search \"old text\" --replace \"new text\"\n\n# Read specific lines\nread_message_lines --message_id 1 --start_line 10 --end_line 20\n```\n\n## š Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `add_message_to_queue` | Add a new message to the batch processing queue |\n| `list_queue_messages` | List and filter messages in the batch queue |\n| `edit_queue_message` | Edit an existing message in the queue |\n| `delete_queue_message` | Delete a message from the queue |\n| `add_file_to_message` | Add file content to an existing queue message |\n| `edit_message_content` | Edit message content using find and replace |\n| `read_message_lines` | Read specific lines from a queue message |\n| `process_batch` | Send pending messages as a batch job |\n| `check_batch_status` | Check the status of batch jobs |\n| `search_responses` | Search through completed batch responses |\n| `configure_provider` | Configure API keys and settings |\n| `export_messages` | Export queue messages to file |\n| `import_messages` | Import messages from JSON file |\n| `status_and_process` | Check status and optionally process batches |\n\n## Example Workflows\n\n### Basic Batch Processing\n1. Add messages to queue:\n ```\n add_message_to_queue --content \"Analyze this data and provide insights\" --provider openai --model gpt-4\n ```\n\n2. Add file context:\n ```\n add_file_to_message --message_id 1 --file_path /path/to/data.csv\n ```\n\n3. Process batch:\n ```\n process_batch --provider openai\n ```\n\n4. Check status:\n ```\n check_batch_status\n ```\n\n### File Analysis Workflow\n1. Create analysis message:\n ```\n add_message_to_queue --content \"Calculate CPM for the following campaign data:\" --provider anthropic\n ```\n\n2. Add CSV data:\n ```\n add_file_to_message --message_id 1 --file_path /path/to/campaign_data.csv\n ```\n\n3. Edit message to improve prompt:\n ```\n edit_message_content --message_id 1 --search \"Calculate CPM\" --replace \"Calculate CPM (Cost Per Mille) and provide detailed analysis with recommendations\"\n ```\n\n4. Process the batch:\n ```\n process_batch --provider anthropic\n ```\n\n### Response Management\n1. Search responses:\n ```\n search_responses --query \"CPM analysis\" --provider anthropic\n ```\n\n2. Read specific parts of messages:\n ```\n read_message_lines --message_id 1 --start_line 5 --end_line 15\n ```\n\n## XML Response Format\n\nThe system uses XML wrapping for responses and file content:\n\n### File Content Format\n```xml\n\nfile content here\n\n```\n\n### Response Format\n```xml\n\nLLM response content here\n\n```\n\n## š¾ Database\n\nThe server uses SQLite for persistent storage. By default, the database is created at:\n- `~/.batch-llm-mcp/batch_queue.db`\n\nYou can customize the location using environment variables:\n- `BATCH_LLM_DATA_DIR`: Base directory for all data\n- `BATCH_LLM_DB_PATH`: Specific database file path\n\n### Database Schema\n\n#### queue_messages\n- `id`: Primary key\n- `content`: Message content/prompt\n- `provider`: LLM provider (openai, anthropic, gemini, mistral)\n- `model`: Specific model name\n- `status`: pending, processing, completed, failed\n- `created_at`, `updated_at`: Timestamps\n- `batch_id`: Associated batch job ID\n- `response`: LLM response\n- `metadata`: JSON metadata\n- `error_message`: Error details if failed\n\n#### batch_jobs\n- `id`: Batch job ID\n- `provider`: LLM provider\n- `status`: pending, processing, completed, failed\n- `created_at`, `completed_at`: Timestamps\n- `message_count`: Number of messages in batch\n- `metadata`: Job metadata\n- `provider_batch_id`: Provider's batch ID\n- `error_message`: Error details if failed\n\n## š§ Development\n\n### Project Structure\n```\nbatch-message-mcp/\nāāā index.js # Main MCP server\nāāā package.json # Dependencies and scripts\nāāā .env.example # Environment variables template\nāāā .gitignore # Git ignore rules\nāāā README.md # This file\n```\n\n### Testing\n```bash\n# Install dependencies\nnpm install\n\n# Run the server\nnpm start\n\n# Test with MCP client or direct stdio communication\n```\n\n## š¤ Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## š License\n\nMIT License - see LICENSE file for details.\n\n## š Support\n\n- Create an issue on GitHub for bugs or feature requests\n- Check the documentation for common questions\n- Review the `.env.example` file for configuration options\n\n## š Related\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Claude Desktop](https://claude.ai/desktop)\n- [OpenAI Batch API](https://platform.openai.com/docs/guides/batch)\n- [Anthropic API](https://docs.anthropic.com/)\n\n---\n\n**Note**: This server provides a simulation of batch processing. For production use with real provider batch APIs, additional implementation of provider-specific batch submission and retrieval logic would be required.\n\n\n**Important Provider Notes**:\n\n- **Mistral AI**: Fully supported with real batch processing API integration\n- **XAI**: Removed from supported providers as they don't offer batch processing API (only real-time calls)\n- **OpenAI, Anthropic, Gemini**: Currently use simulation mode (ready for real batch API integration)\n","readmeFilename":"README.md"}