elasticsearch-mcp-server

JacobZoarets/elasticsearch-mcp-server

3.1

If you are the rightful owner of elasticsearch-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Model Context Protocol (MCP) server is designed to facilitate seamless integration with AI tools, providing structured document management and search capabilities.

Tools
5
Resources
0
Prompts
0

Elasticsearch MCP Server

A complete system with Elasticsearch, Node.js CRUD API, and MCP server integration for seamless document management and search capabilities.

Architecture

  • Elasticsearch: Search engine running in Docker with sample data
  • API Server: Node.js/TypeScript server with RESTful CRUD operations
  • MCP Server: Model Context Protocol server for external integration with AI tools

Features

Elasticsearch

  • Full-text search with relevance scoring
  • Document indexing with custom mappings
  • Persistent data storage
  • Health monitoring

API Server

  • RESTful CRUD operations for documents
  • Input validation and error handling
  • Comprehensive logging
  • Health check endpoints

MCP Server

  • 5 MCP tools for document operations:
    • create_document: Create new documents
    • get_document: Retrieve documents by ID
    • update_document: Update existing documents
    • delete_document: Delete documents
    • search_documents: Full-text search with filters
  • JSON schema validation for all tools
  • Structured error responses

Quick Start

Automated Setup (Recommended)

Linux/macOS:

./scripts/start.sh

Windows:

scripts\start.bat

Manual Setup

  1. Setup Environment:

    cp api/.env.example api/.env
cp mcp/.env.example mcp/.env

  2. Start the System:

    docker-compose up -d

  3. Verify Services:

API Endpoints

Documents

  • POST /documents - Create document
  • GET /documents/:id - Get document by ID
  • PUT /documents/:id - Update document
  • DELETE /documents/:id - Delete document
  • GET /documents/search - Search documents

Health

  • GET /health - Service health check

Example API Usage

# Create a document
curl -X POST http://localhost:3000/documents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Document",
    "content": "Document content here",
    "tags": ["example", "test"],
    "metadata": {"author": "user"}
  }'

# Search documents
curl "http://localhost:3000/documents/search?query=document&limit=5"

MCP Integration

Using with MCP Inspector

  1. Setup MCP Server:

    ./scripts/mcp-setup.sh  # Linux/macOS

  2. Install MCP Inspector:

    npm install -g @modelcontextprotocol/inspector

  3. Start MCP Server:

    cd mcp && npm start

  4. Connect Inspector:

    mcp-inspector node mcp/dist/index.js

Using with Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/mcp/dist/index.js"],
      "env": {
        "API_URL": "http://localhost:3000"
      }
    }
  }
}

Development

API Development

cd api
npm install
npm run dev        # Development server
npm test          # Run tests
npm run build     # Build for production

MCP Development

cd mcp
npm install
npm run dev        # Development server
npm test          # Run tests
npm run build     # Build for production

Testing

Unit Tests

# API tests
cd api && npm test

# MCP tests
cd mcp && npm test

Integration Tests

Automated Testing:

./scripts/test.sh  # Linux/macOS

Manual Testing:

# Start test environment
docker-compose -f docker-compose.test.yml up -d

# Run integration tests
cd tests/integration
npm install
npm test

# Cleanup
docker-compose -f docker-compose.test.yml down

Configuration

Environment Variables

API Server (.env):

NODE_ENV=development
PORT=3000
ELASTICSEARCH_URL=http://localhost:9200
ELASTICSEARCH_INDEX=documents
LOG_LEVEL=info

MCP Server (.env):

NODE_ENV=development
API_URL=http://localhost:3000
MCP_PORT=3001
LOG_LEVEL=info

Document Schema

interface Document {
  id?: string;
  title: string;
  content: string;
  tags: string[];
  created_at: Date;
  updated_at: Date;
  metadata?: Record<string, any>;
}

Error Handling

The system provides comprehensive error handling:

  • Validation Errors: Input validation with detailed field-level errors
  • Not Found Errors: Proper 404 responses for missing documents
  • Elasticsearch Errors: Connection and query error handling
  • MCP Errors: Structured error responses following MCP protocol

Monitoring

Health Checks

  • API health endpoint: GET /health
  • Elasticsearch cluster health monitoring
  • Docker container health checks

Logging

  • Structured JSON logging
  • Request/response logging
  • Error tracking with stack traces
  • Configurable log levels

Production Deployment

  1. Build Images:

    docker-compose build

  2. Set Production Environment:

    export NODE_ENV=production

  3. Deploy:

    docker-compose up -d

Troubleshooting

Common Issues

  1. Elasticsearch not starting:

    • Check memory limits (requires at least 512MB)
    • Verify Docker has sufficient resources

  2. API connection errors:

    • Ensure Elasticsearch is healthy before starting API
    • Check network connectivity between containers

  3. MCP tools not working:

    • Verify API server is running and healthy
    • Check MCP server logs for connection errors

Logs

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f elasticsearch
docker-compose logs -f api

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Submit a pull request

License

MIT License