# 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)
