# MindsDB MySQL MCP Server

MCP server for MindsDB that connects via MySQL protocol (port 47335), providing reliable tools for Claude Code and Desktop.

## Why MySQL over SSE/HTTP?

- MySQL protocol is stable and well-tested
- No async event loop issues (the "this event loop is already running" errors)
- Better error messages and debugging
- Works reliably with knowledge base queries

## Installation

```bash
cd mcp/mindsdb-mysql
npm install
npm run build
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MINDSDB_HOST` | `127.0.0.1` | MindsDB server host |
| `MINDSDB_PORT` | `47335` | MindsDB MySQL port |
| `MINDSDB_USER` | `mindsdb` | Username (use your MindsDB Cloud email for cloud instances) |
| `MINDSDB_PASSWORD` | (empty) | Password (required for MindsDB Cloud) |

### Claude Code (`~/.claude.json`)

```json
{
  "mcpServers": {
    "mindsdb": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/mindsdb-mysql/dist/index.js"
      ],
      "env": {
        "MINDSDB_HOST": "localhost",
        "MINDSDB_PORT": "47335",
        "MINDSDB_USER": "mindsdb",
        "MINDSDB_PASSWORD": ""
      }
    }
  }
}
```

For MindsDB Cloud, use your email as `MINDSDB_USER` and your password for `MINDSDB_PASSWORD`.

### Claude Desktop (`claude_desktop_config.json`)

Same configuration, add to the `mcpServers` object.

## Available Tools (11)

### 1. `query` - Execute SQL
Execute any MindsDB SQL query. Use this for custom queries not covered by other tools.

```typescript
query(sql: string, database?: string): QueryResult
```

### 2. `list_databases` - List Data Sources
List all databases/data sources in MindsDB.

```typescript
list_databases(): string[]
```

### 3. `list_knowledge_bases` - List KBs
List all knowledge bases in MindsDB.

```typescript
list_knowledge_bases(): KnowledgeBase[]
```

### 4. `describe` - Describe Any Object
Describe a model, table, or knowledge base. Returns column information.

```typescript
describe(name: string, database?: string): Description
```

### 5. `search_kb` - Search Knowledge Base
Search a knowledge base using hybrid semantic + keyword search.

```typescript
search_kb(
  kb_name: string,
  question: string,
  limit?: number,         // default: 10
  alpha?: number,         // default: 0.5 (0=keyword, 1=semantic)
  min_relevance?: number, // default: 0
  metadata_filter?: Record<string, string>
): SearchResult[]
```

### 6. `insert_kb` - Insert Data into Knowledge Base
Insert data into a knowledge base from a source query.

```typescript
insert_kb(
  kb_name: string,
  source_query: string,   // e.g., "SELECT id, content FROM mydb.docs"
  batch_size?: number,    // default: 1000
  threads?: number,       // default: 1
  skip_existing?: boolean // default: false
): { rows_inserted: number }
```

### 7. `create_kb` - Create Knowledge Base
Create a new knowledge base with embedding model configuration.

```typescript
create_kb(
  name: string,
  embedding_model: {
    provider: string,     // openai, azure, google, ollama
    model_name: string,
    api_key?: string
  },
  content_columns: string[],
  metadata_columns?: string[],
  id_column?: string,
  reranking_model?: {...},
  storage?: string        // default: chromadb
): { kb_name: string }
```

### 8. `list_jobs` - List Scheduled Jobs
List all scheduled jobs in MindsDB.

```typescript
list_jobs(): Job[]
```

### 9. `create_job` - Schedule Recurring Query
Create a scheduled job to run a query at regular intervals.

```typescript
create_job(
  name: string,
  query: string,          // SQL to execute
  every: string,          // e.g., "1 hour", "1 day"
  start?: string,         // ISO datetime
  end?: string            // ISO datetime
): { job_name: string }
```

### 10. `list_tables` - List Tables
List all tables in a specific database.

```typescript
list_tables(database: string): string[]
```

### 11. `connect_database` - Connect External Data Source
Connect an external database as a data source in MindsDB.

```typescript
connect_database(
  name: string,
  engine: string,         // postgres, mysql, mongodb, etc.
  parameters: {
    host: string,
    port: number,
    database: string,
    user: string,
    password: string
  }
): { database_name: string }
```

## Testing

### With MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

Or with a remote MindsDB instance:

```bash
MINDSDB_HOST=your-mindsdb-host MINDSDB_PORT=47335 \
  npx @modelcontextprotocol/inspector node dist/index.js
```

### Manual verification

After configuring Claude Code, restart and verify:

```
# In Claude Code, these tools should be available:
mcp__mindsdb__list_databases
mcp__mindsdb__list_knowledge_bases
mcp__mindsdb__search_kb
mcp__mindsdb__query
# ... etc.
```

## MindsDB SQL Reference

### Knowledge Base Query

```sql
-- Semantic search
SELECT * FROM my_kb WHERE content = 'search phrase' LIMIT 10;

-- With relevance filter
SELECT * FROM my_kb WHERE content = 'query' AND relevance >= 0.5;

-- Hybrid search (keyword + semantic)
SELECT * FROM my_kb WHERE content = 'query' AND hybrid_search_alpha = 0.8;

-- Metadata filter
SELECT * FROM my_kb WHERE content = 'query' AND metadata_column = 'value';
```

### Output Columns

- `chunk_id`: `<id>:<chunk_number>of<total>:<start_char>to<end_char>`
- `chunk_content`: The text content
- `relevance`: 0-1 score (higher = better match)
- `distance`: Vector distance (lower = closer)