1. 項目概述當AI開始“理解”你的數據庫最近在折騰AI編程助手特別是Cursor發現一個挺有意思的現象你跟它說“幫我查一下上個月的訂單數據”它大概率會給你編一段看起來像模像樣的SQL但數據庫里可能根本沒有orders這個表或者字段名完全對不上。這感覺就像讓一個頂尖的廚師去一個完全陌生的廚房做飯他刀工火候再好不知道食材和調料放在哪兒也做不出像樣的菜。這個問題的核心就是AI模型LLM與你的私有數據、特定工具之間存在著一道難以逾越的“信息鴻溝”。而MCPModel Context Protocol就是為填平這道鴻溝而生的“橋梁協議”。它不是什么高深莫測的新框架你可以把它理解為一套標準化的“插座”和“插頭”規范。你的數據庫比如MySQL、你的API、你的內部工具只要按照MCP的標準做成一個“Server”服務器即插頭就能被支持MCP的“Client”客戶端即插座如Cursor、Claude Desktop識別并調用。于是AI助手不再是一個只會空想的“理論家”它變成了一個能直接操作你數據庫、調用你內部API的“實干家”。這個項目要探討的就是如何親手搭建這座橋讓Cursor這類AI編程助手通過MCP協議真正“理解”并操作你的MySQL數據庫。這不是簡單的插件安裝而是一套讓AI融入你現有技術棧工作流的系統工程。我會從為什么需要MCP講起帶你一步步拆解MCP的核心組件手把手實現一個連接MySQL的MCP Server并最終在Cursor中驗證效果分享其中踩過的坑和總結出的實戰經驗。2. MCP協議核心拆解AI的“手”和“眼”要理解MCP如何工作我們得先拋開那些復雜的術語把它想象成給AI安裝“手”和“眼”。LLM本身是一個強大的“大腦”它擅長理解和生成語言但它沒有“手”去操作數據庫也沒有“眼”去查看服務器狀態。MCP協議的核心就是定義了一套標準方式讓“大腦”可以安全、可控地指揮各種各樣的“手”和“眼”。2.1 核心組件與通信模型MCP的架構非常清晰主要包含三個角色它們之間的通信基于JSON-RPC over stdio標準輸入輸出或SSE服務器發送事件這種設計讓它極其輕量和通用。MCP Client客戶端這是AI能力的消費方。比如Cursor編輯器、Claude Desktop應用或者任何集成了MCP SDK的應用。Client的角色是向用戶提供AI交互界面并向MCP Server發起工具調用或內容讀取的請求。你可以把它看作“大腦”的對外接口。MCP Server服務器這是能力的提供方。它封裝了對特定資源如MySQL數據庫、文件系統、天氣API的操作邏輯。一個Server可以提供一個或多個“工具”Tools或“資源”Resources。它就像一個個專屬的“手”或“眼”。我們本項目要構建的就是一個MySQL Server。MCP Host宿主這是連接Client和Server的“調度中心”或“運行時環境”。它負責啟動和管理一個或多個MCP Server并在Client和Server之間路由消息。Claude Desktop、Cursor內置了MCP Host。在開發時我們也會使用官方工具modelcontextprotocol/sdk來模擬Host進行測試。它們之間的關系可以用一個簡單的場景來類比你想讓AI助手幫你查數據Client發出指令 - MCP Host收到指令知道該找誰找到MySQL Server - MySQL Server執行查詢手部動作 - 結果通過Host返回給Client - AI大腦將結果組織成自然語言回復給你。2.2 能力抽象Tools與ResourcesMCP協議將Server能提供的能力抽象為兩大類這是理解其功能邊界的關鍵Tools工具代表一個可執行的動作。調用Tools就像讓AI“用手做一件事”。每個Tool都有明確的名稱、描述、輸入參數JSON Schema定義和輸出。例如我們的MySQL Server可以提供execute_query: 執行一條SELECT查詢語句。list_tables: 列出數據庫中的所有表。get_table_schema: 獲取指定表的字段結構。 當用戶在Cursor里說“列出用戶表的前10條數據”CursorClient就會調用MySQL Server的execute_query這個Tool并傳入參數sql: SELECT * FROM users LIMIT 10。Resources資源代表可讀取的靜態或動態內容。讀取Resources就像讓AI“用眼查看一份資料”。每個Resource有一個唯一的uri如mysql://my_db/users/schema和對應的文本內容。例如我們可以將數據庫的表結構定義作為Resource提供mysql://localhost:3306/mydb/tables資源的內容是所有表名的列表。mysql://localhost:3306/mydb/tables/users資源的內容是users表的CREATE TABLE語句。 這樣AI在回答問題前可以先“閱讀”這些Resource來了解數據庫結構從而生成更準確的SQL。注意一個常見的誤解是認為MCP Server必須同時提供Tools和Resources。實際上這取決于你的需求。對于數據庫操作Tools執行查詢是核心而提供Resources表結構則能極大提升AI生成SQL的準確性是強烈推薦的做法。2.3 為什么是Stdio/SSE安全與集成的考量你可能會問為什么用Stdio標準輸入輸出這種“古老”的方式通信而不是更常見的HTTP API這恰恰是MCP設計的精妙之處。無網絡依賴與極致簡化Stdio通信發生在同一臺機器的進程之間無需處理網絡端口、防火墻、HTTPS證書等復雜問題。這使得MCP Server可以像本地命令行工具一樣簡單部署和運行。安全性由于通信不暴露網絡端口外部無法直接訪問MCP Server減少了攻擊面。權限完全由啟動Server的Host環境控制。進程生命周期管理Host可以輕松地啟動、停止和監控Server進程。當Client斷開連接時Host可以清理所有相關Server進程避免資源泄漏。SSE用于流式響應對于需要長時間運行或流式返回結果的操作例如監控日志MCP支持SSE允許Server逐步返回數據用戶體驗更好。這種設計讓MCP在提供強大擴展能力的同時保持了本地化工具應有的簡潔和安全特別適合集成到桌面AI應用中。3. 構建MySQL MCP Server從零到一的實戰理論講完了我們動手建一個。我將使用Node.js和官方SDK來構建因為這是目前最成熟、文檔最全的路徑。別擔心即使你不是Node專家跟著步驟也能走通。3.1 環境準備與項目初始化首先確保你的開發環境已經就緒Node.js版本18或以上。可以去官網下載安裝。MySQL本地安裝一個MySQL實例5.7或8.0均可并創建一個測試數據庫和表。比如CREATE DATABASE mcp_demo; USE mcp_demo; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL, email VARCHAR(100) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); INSERT INTO users (username, email) VALUES (alice, aliceexample.com), (bob, bobexample.com);代碼編輯器VS Code或你喜歡的任何編輯器。接下來創建項目目錄并初始化mkdir mcp-mysql-server cd mcp-mysql-server npm init -y安裝核心依賴npm install modelcontextprotocol/sdk mysql2modelcontextprotocol/sdk官方SDK提供了構建Server和Client的所有工具類。mysql2一個性能更好的MySQL客戶端庫支持Promise。3.2 Server核心邏輯實現我們創建一個server.js文件這是整個Server的核心。第一步引入依賴并建立數據庫連接const { Server } require(modelcontextprotocol/sdk/server/index.js); const { StdioServerTransport } require(modelcontextprotocol/sdk/server/stdio.js); const mysql require(mysql2/promise); // 使用Promise接口 // 創建MySQL連接池生產環境建議從環境變量讀取配置 const pool mysql.createPool({ host: localhost, user: root, // 替換為你的用戶名 password: yourpassword, // 替換為你的密碼 database: mcp_demo, waitForConnections: true, connectionLimit: 10, queueLimit: 0 });這里使用連接池而不是單連接是為了避免在高頻調用下出現連接數耗盡的問題。連接參數務必通過環境變量如process.env.DB_HOST管理切勿硬編碼在代碼中。第二步初始化MCP Server并聲明能力// 初始化Server const server new Server( { name: mysql-server, version: 0.1.0, }, { capabilities: { tools: {}, // 我們將在這里注冊工具 resources: {} // 我們將在這里注冊資源 } } ); // 定義工具執行SQL查詢 server.setRequestHandler(tools/list, async () { return { tools: [ { name: execute_query, description: Execute a SELECT SQL query against the MySQL database. Use this for reading data., inputSchema: { type: object, properties: { sql: { type: string, description: The SELECT SQL query to execute. } }, required: [sql] } }, { name: list_tables, description: List all tables in the connected database., inputSchema: { type: object, properties: {} } // 無參數 }, { name: get_table_schema, description: Get the CREATE TABLE statement (schema) for a specific table., inputSchema: { type: object, properties: { tableName: { type: string, description: Name of the table. } }, required: [tableName] } } ] }; });這里我們定義了三個工具。注意execute_query的描述中強調了SELECT這是一種安全實踐避免AI無意中執行DELETE或DROP語句。在生產環境中你需要更嚴格的SQL解析和白名單機制。第三步實現工具調用的處理邏輯這是Server的“肌肉”真正執行操作的地方。// 處理工具調用請求 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; try { switch (name) { case execute_query: { const { sql } args; // 簡單的安全校驗只允許SELECT查詢可根據需要放寬 if (!sql.trim().toUpperCase().startsWith(SELECT)) { throw new Error(Only SELECT queries are allowed for safety.); } const [rows] await pool.query(sql); return { content: [ { type: text, text: JSON.stringify(rows, null, 2) // 美化輸出JSON } ] }; } case list_tables: { const [rows] await pool.query(SHOW TABLES); const tableList rows.map(row Object.values(row)[0]).join(\n); return { content: [{ type: text, text: Tables in database:\n${tableList} }] }; } case get_table_schema: { const { tableName } args; const [rows] await pool.query(SHOW CREATE TABLE ${tableName}); const schema rows[0]?.[Create Table]; return { content: [{ type: text, text: schema || Table ${tableName} not found. }] }; } default: throw new Error(Unknown tool: ${name}); } } catch (error) { // 返回結構化的錯誤信息幫助AI和用戶調試 return { content: [{ type: text, text: Error: ${error.message} }], isError: true }; } });關鍵點在于錯誤處理。必須用try...catch包裹并返回格式化的錯誤信息。直接拋出異常可能導致Server進程崩潰破壞整個MCP會話。第四步實現資源讀取可選但推薦為了讓AI更好地“理解”數據庫結構我們提供資源。// 聲明可用的資源 server.setRequestHandler(resources/list, async (request) { const { uri } request.params; // 如果請求了根URI列出所有表資源 if (!uri || uri mysql://schema/) { const [tables] await pool.query(SHOW TABLES); const resources tables.map(table ({ uri: mysql://schema/${Object.values(table)[0]}, name: Schema of table: ${Object.values(table)[0]}, mimeType: text/plain })); // 添加一個總覽資源 resources.unshift({ uri: mysql://schema/, name: Database Schema Overview, mimeType: text/plain }); return { resources }; } return { resources: [] }; }); // 處理資源讀取請求 server.setRequestHandler(resources/read, async (request) { const { uri } request.params; if (uri mysql://schema/) { const [tables] await pool.query(SHOW TABLES); const tableNames tables.map(row - ${Object.values(row)[0]}).join(\n); return { contents: [{ uri, mimeType: text/plain, text: Available tables:\n${tableNames} }] }; } // 匹配表結構URI如 mysql://schema/users const match uri.match(/^mysql:\/\/schema\/(.)$/); if (match) { const tableName match[1]; const [rows] await pool.query(SHOW CREATE TABLE ??, [tableName]); const schema rows[0]?.[Create Table]; return { contents: [{ uri, mimeType: text/plain, text: schema || // Table ${tableName} not found or inaccessible. }] }; } return { contents: [{ uri, mimeType: text/plain, text: // Resource not found: ${uri} }] }; });這里我們設計了一個簡單的資源URI方案mysql://schema/列出所有表mysql://schema/{tableName}獲取具體表結構。這種設計讓AI能按需瀏覽數據庫元數據。第五步啟動Server// 啟動Server使用stdio傳輸 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MySQL MCP Server running on stdio...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });console.error用于輸出日志因為MCP協議使用stdin/stdout進行通信常規的console.log會干擾協議消息。3.3 本地測試與調試在配置Cursor之前強烈建議先本地測試Server是否正常工作。我們可以寫一個簡單的測試Client腳本test_client.jsconst { Client } require(modelcontextprotocol/sdk/client/index.js); const { StdioClientTransport } require(modelcontextprotocol/sdk/client/stdio.js); const { spawn } require(child_process); async function test() { // 啟動Server進程 const serverProcess spawn(node, [server.js]); const transport new StdioClientTransport(serverProcess); const client new Client( { name: test-client, version: 1.0.0 }, { capabilities: {} } ); await client.connect(transport); // 測試列出工具 const tools await client.listTools(); console.log(Available tools:, tools.tools.map(t t.name)); // 測試列出表 const result await client.callTool({ name: list_tables, arguments: {} }); console.log(List tables result:, result.content[0].text); // 測試查詢 const queryResult await client.callTool({ name: execute_query, arguments: { sql: SELECT * FROM users LIMIT 1 } }); console.log(Query result:, queryResult.content[0].text); await client.close(); serverProcess.kill(); } test().catch(console.error);運行node test_client.js如果看到工具列表和查詢結果恭喜你Server端基本功能已就緒。這個測試步驟能幫你提前發現并解決90%的配置和代碼邏輯問題。4. 在Cursor中集成與配置讓AI助手“上手”Server準備好了現在要讓Cursor這個“大腦”能用上我們造的“手”。Cursor內置了MCP Host支持配置過程直觀。4.1 配置Cursor的MCP設置Cursor的配置主要通過一個JSON文件完成。文件位置通常如下macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json如果目錄或文件不存在手動創建即可。我們需要編輯這個mcp.json文件將我們的MySQL Server添加進去。{ mcpServers: { mysql-local: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-mysql-server/server.js ], env: { DB_HOST: localhost, DB_USER: root, DB_PASSWORD: yourpassword, DB_DATABASE: mcp_demo } } } }配置詳解與避坑指南絕對路徑是必須的args里的路徑必須是絕對路徑。相對路徑在Cursor的運行時環境中無法正確解析。這是新手最容易踩的坑。在macOS/Linux上可以用pwd命令獲取在Windows上需要完整的盤符路徑。環境變量管理敏感信息永遠不要在配置文件中硬編碼數據庫密碼。通過env字段傳入環境變量然后在server.js中通過process.env.DB_PASSWORD讀取。這樣更安全也便于在不同環境開發、測試間切換。命令與參數command是你系統里可執行命令的名字如node、python3。args是一個數組第一個元素通常是你的腳本文件絕對路徑。如果你的Server是用其他語言如Python、Go寫的這里就需要相應調整。多個ServermcpServers對象可以配置多個Server。比如你還可以同時配置一個用于搜索的tavily-mcpServer。Cursor會自動管理它們。4.2 驗證與使用對話式數據查詢保存mcp.json后完全重啟Cursor。這是關鍵一步因為Cursor只在啟動時讀取這個配置文件。重啟后打開Cursor的聊天界面通常通過Cmd/Ctrl K觸發。如果配置成功你應該能在輸入框下方或模型選擇區域看到類似“可用工具”或“Connected tools”的提示或者至少不會報錯。現在進行一場真正的對話測試你“我們數據庫里有哪些表”Cursor識別到需要查詢數據庫自動調用list_tables工具 “根據查詢數據庫中有以下表users, products, orders。”你“看看users表的結構是什么樣的”Cursor調用get_table_schema工具 “users表的結構如下CREATE TABLE users (id int, name varchar(100), ...)”你“幫我查一下最近創建的5個用戶按時間倒序排列。”Cursor思考后組合已知的表結構和字段生成SQL并調用execute_query “好的查詢語句為SELECT * FROM users ORDER BY created_at DESC LIMIT 5結果如下[...]”這個過程是自動的。Cursor背后的AI模型會根據你的自然語言描述判斷意圖選擇合適的工具并生成正確的調用參數。你不再需要手動編寫或粘貼SQLAI真正成為了你和數據庫之間的“翻譯官”和“操作員”。4.3 高級配置安全性與性能調優基礎配置跑通后為了投入實際使用還需要考慮以下幾點權限最小化在MySQL中為MCP Server創建一個專用用戶只授予它必要的SELECT權限甚至可以通過視圖VIEW來限制其可訪問的數據范圍。絕對不要使用root賬戶。CREATE USER mcp_clientlocalhost IDENTIFIED BY strong_password; GRANT SELECT ON mcp_demo.* TO mcp_clientlocalhost; -- 或者更細粒度 GRANT SELECT ON mcp_demo.public_view TO mcp_clientlocalhost;SQL注入防護我們的簡單示例只做了SELECT前綴檢查這是遠遠不夠的。生產環境中應考慮使用參數化查詢mysql2庫本身支持pool.query(SELECT * FROM users WHERE id ?, [userId])但這對AI動態生成的SQL不直接適用。實現一個簡單的SQL解析器或使用sql-parser等庫進行語法樹白名單校驗只允許無副作用的查詢語句。限制查詢的復雜度如設置最大返回行數LIMIT、禁用多表JOIN或子查詢等。連接池與超時確保MySQL連接池配置合理connectionLimit并在Server端為數據庫查詢設置超時SET SESSION MAX_EXECUTION_TIME10000防止一個慢查詢拖死整個Server。日志與監控在Server中添加詳細的日志記錄工具調用、查詢語句、執行時間、錯誤信息便于后期審計和性能分析。可以將日志輸出到文件或標準錯誤。5. 常見問題、排查與進階思考即使按照步驟操作也難免會遇到問題。這里記錄一些我實踐中遇到的典型情況和解決方法。5.1 問題排查清單問題現象可能原因排查步驟Cursor啟動后無工具提示或聊天中AI不調用工具。1.mcp.json配置文件路徑錯誤或格式錯誤。2. Server啟動失敗如Node路徑錯誤、依賴未安裝。3. Cursor未重啟。1. 檢查mcp.json的JSON語法可用在線校驗工具。2. 在終端手動運行配置中的命令如node /path/to/server.js看是否報錯。3.務必徹底關閉Cursor并重新打開。AI調用了工具但返回“Error”或超時。1. 數據庫連接失敗主機、端口、密碼錯誤。2. SQL語句執行錯誤權限不足、語法錯誤。3. Server代碼邏輯錯誤或未處理異常。1. 使用test_client.js進行本地測試查看具體錯誤信息。2. 檢查Server代碼中的錯誤處理邏輯確保所有await都有try...catch。3. 查看Cursor的開發者控制臺Help - Toggle Developer Tools中的Console日志。工具調用成功但AI不理解結果或胡亂回答。1. 工具返回的數據格式太復雜如嵌套很深的JSON。2. AI的上下文長度有限結果太長被截斷。1. 優化工具返回內容盡量簡潔、結構化。例如將數據庫結果以Markdown表格形式返回比純JSON更易讀。2. 在工具中內置總結或采樣邏輯比如只返回前10行并提供總行數。配置多個Server后AI混淆了工具。不同Server提供的工具名稱或功能相似。在定義工具時使用更具體、包含領域前綴的名稱如mysql_execute_query、postgres_list_tables。在工具描述中也要清晰說明其邊界。5.2 性能優化與擴展方向當基本功能穩定后可以考慮以下優化和擴展讓這個“AI助手”更強大、更智能提供智能提示資源除了基本的表結構可以創建更豐富的Resources。例如mysql://docs/query_examples: 提供一個文檔里面寫一些常用的查詢示例和業務邏輯說明。mysql://stats/table_row_counts: 動態生成一個資源顯示每個表的大致數據量幫助AI決定是否要加LIMIT。這些資源會被AI在思考時自動讀取作為背景知識顯著提升生成SQL的準確性和合理性。實現更復雜的工具不止于查詢可以開發需要邏輯判斷的工具。analyze_query_plan: 接收一個查詢語句返回其EXPLAIN結果讓AI能判斷查詢性能。suggest_index: 基于慢查詢日志或當前查詢模式讓AI給出索引優化建議雖然最終執行需DBA確認。這些工具將AI從“操作員”提升為“初級分析師”。與其他MCP Server聯動MCP的魅力在于組合。你可以同時運行MySQL Server處理數據查詢。文件系統Server讓AI能讀取項目代碼文件。Git Server讓AI能查看提交歷史。Web Search Server如Tavily讓AI能聯網搜索錯誤信息。 這樣你對AI說“根據最近一周的錯誤日志文件去數據庫里查查關聯的用戶訂單MySQL然后看看官方文檔搜索里有沒有解決方案”它就能串聯起多個工具完成一個復雜的工作流。Server實現的多樣性我們的示例是Node.js但MCP協議是語言無關的。社區已經有Python、Go、Rust等多種語言的SDK和示例。你可以根據團隊的技術棧選擇最合適的語言來實現甚至可以封裝現有的腳本或工具為MCP Server極大地降低了集成成本。通過MCP將Cursor與MySQL連接只是一個起點。它展示了一種范式如何將AI大模型強大的語言理解和生成能力與組織內部具體、私有、結構化的工具和數據安全地結合起來。這不僅僅是寫一個插件而是在構建一套讓AI智能體AI Agent真正落地、融入日常研發工作流的基礎設施。當你習慣了用自然語言讓AI幫你查數據、看日志、分析代碼變更時你會發現開發工作的交互方式正在發生靜默但深刻的變革。 基于MCP協議構建MySQL MCP Server，讓AI編程助手安全操作數據庫
1. 項目概述當AI開始“理解”你的數據庫最近在折騰AI編程助手特別是Cursor發現一個挺有意思的現象你跟它說“幫我查一下上個月的訂單數據”它大概率會給你編一段看起來像模像樣的SQL但數據庫里可能根本沒有orders這個表或者字段名完全對不上。這感覺就像讓一個頂尖的廚師去一個完全陌生的廚房做飯他刀工火候再好不知道食材和調料放在哪兒也做不出像樣的菜。這個問題的核心就是AI模型LLM與你的私有數據、特定工具之間存在著一道難以逾越的“信息鴻溝”。而MCPModel Context Protocol就是為填平這道鴻溝而生的“橋梁協議”。它不是什么高深莫測的新框架你可以把它理解為一套標準化的“插座”和“插頭”規范。你的數據庫比如MySQL、你的API、你的內部工具只要按照MCP的標準做成一個“Server”服務器即插頭就能被支持MCP的“Client”客戶端即插座如Cursor、Claude Desktop識別并調用。于是AI助手不再是一個只會空想的“理論家”它變成了一個能直接操作你數據庫、調用你內部API的“實干家”。這個項目要探討的就是如何親手搭建這座橋讓Cursor這類AI編程助手通過MCP協議真正“理解”并操作你的MySQL數據庫。這不是簡單的插件安裝而是一套讓AI融入你現有技術棧工作流的系統工程。我會從為什么需要MCP講起帶你一步步拆解MCP的核心組件手把手實現一個連接MySQL的MCP Server并最終在Cursor中驗證效果分享其中踩過的坑和總結出的實戰經驗。2. MCP協議核心拆解AI的“手”和“眼”要理解MCP如何工作我們得先拋開那些復雜的術語把它想象成給AI安裝“手”和“眼”。LLM本身是一個強大的“大腦”它擅長理解和生成語言但它沒有“手”去操作數據庫也沒有“眼”去查看服務器狀態。MCP協議的核心就是定義了一套標準方式讓“大腦”可以安全、可控地指揮各種各樣的“手”和“眼”。2.1 核心組件與通信模型MCP的架構非常清晰主要包含三個角色它們之間的通信基于JSON-RPC over stdio標準輸入輸出或SSE服務器發送事件這種設計讓它極其輕量和通用。MCP Client客戶端這是AI能力的消費方。比如Cursor編輯器、Claude Desktop應用或者任何集成了MCP SDK的應用。Client的角色是向用戶提供AI交互界面并向MCP Server發起工具調用或內容讀取的請求。你可以把它看作“大腦”的對外接口。MCP Server服務器這是能力的提供方。它封裝了對特定資源如MySQL數據庫、文件系統、天氣API的操作邏輯。一個Server可以提供一個或多個“工具”Tools或“資源”Resources。它就像一個個專屬的“手”或“眼”。我們本項目要構建的就是一個MySQL Server。MCP Host宿主這是連接Client和Server的“調度中心”或“運行時環境”。它負責啟動和管理一個或多個MCP Server并在Client和Server之間路由消息。Claude Desktop、Cursor內置了MCP Host。在開發時我們也會使用官方工具modelcontextprotocol/sdk來模擬Host進行測試。它們之間的關系可以用一個簡單的場景來類比你想讓AI助手幫你查數據Client發出指令 - MCP Host收到指令知道該找誰找到MySQL Server - MySQL Server執行查詢手部動作 - 結果通過Host返回給Client - AI大腦將結果組織成自然語言回復給你。2.2 能力抽象Tools與ResourcesMCP協議將Server能提供的能力抽象為兩大類這是理解其功能邊界的關鍵Tools工具代表一個可執行的動作。調用Tools就像讓AI“用手做一件事”。每個Tool都有明確的名稱、描述、輸入參數JSON Schema定義和輸出。例如我們的MySQL Server可以提供execute_query: 執行一條SELECT查詢語句。list_tables: 列出數據庫中的所有表。get_table_schema: 獲取指定表的字段結構。 當用戶在Cursor里說“列出用戶表的前10條數據”CursorClient就會調用MySQL Server的execute_query這個Tool并傳入參數sql: SELECT * FROM users LIMIT 10。Resources資源代表可讀取的靜態或動態內容。讀取Resources就像讓AI“用眼查看一份資料”。每個Resource有一個唯一的uri如mysql://my_db/users/schema和對應的文本內容。例如我們可以將數據庫的表結構定義作為Resource提供mysql://localhost:3306/mydb/tables資源的內容是所有表名的列表。mysql://localhost:3306/mydb/tables/users資源的內容是users表的CREATE TABLE語句。 這樣AI在回答問題前可以先“閱讀”這些Resource來了解數據庫結構從而生成更準確的SQL。注意一個常見的誤解是認為MCP Server必須同時提供Tools和Resources。實際上這取決于你的需求。對于數據庫操作Tools執行查詢是核心而提供Resources表結構則能極大提升AI生成SQL的準確性是強烈推薦的做法。2.3 為什么是Stdio/SSE安全與集成的考量你可能會問為什么用Stdio標準輸入輸出這種“古老”的方式通信而不是更常見的HTTP API這恰恰是MCP設計的精妙之處。無網絡依賴與極致簡化Stdio通信發生在同一臺機器的進程之間無需處理網絡端口、防火墻、HTTPS證書等復雜問題。這使得MCP Server可以像本地命令行工具一樣簡單部署和運行。安全性由于通信不暴露網絡端口外部無法直接訪問MCP Server減少了攻擊面。權限完全由啟動Server的Host環境控制。進程生命周期管理Host可以輕松地啟動、停止和監控Server進程。當Client斷開連接時Host可以清理所有相關Server進程避免資源泄漏。SSE用于流式響應對于需要長時間運行或流式返回結果的操作例如監控日志MCP支持SSE允許Server逐步返回數據用戶體驗更好。這種設計讓MCP在提供強大擴展能力的同時保持了本地化工具應有的簡潔和安全特別適合集成到桌面AI應用中。3. 構建MySQL MCP Server從零到一的實戰理論講完了我們動手建一個。我將使用Node.js和官方SDK來構建因為這是目前最成熟、文檔最全的路徑。別擔心即使你不是Node專家跟著步驟也能走通。3.1 環境準備與項目初始化首先確保你的開發環境已經就緒Node.js版本18或以上。可以去官網下載安裝。MySQL本地安裝一個MySQL實例5.7或8.0均可并創建一個測試數據庫和表。比如CREATE DATABASE mcp_demo; USE mcp_demo; CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) NOT NULL, email VARCHAR(100) NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); INSERT INTO users (username, email) VALUES (alice, aliceexample.com), (bob, bobexample.com);代碼編輯器VS Code或你喜歡的任何編輯器。接下來創建項目目錄并初始化mkdir mcp-mysql-server cd mcp-mysql-server npm init -y安裝核心依賴npm install modelcontextprotocol/sdk mysql2modelcontextprotocol/sdk官方SDK提供了構建Server和Client的所有工具類。mysql2一個性能更好的MySQL客戶端庫支持Promise。3.2 Server核心邏輯實現我們創建一個server.js文件這是整個Server的核心。第一步引入依賴并建立數據庫連接const { Server } require(modelcontextprotocol/sdk/server/index.js); const { StdioServerTransport } require(modelcontextprotocol/sdk/server/stdio.js); const mysql require(mysql2/promise); // 使用Promise接口 // 創建MySQL連接池生產環境建議從環境變量讀取配置 const pool mysql.createPool({ host: localhost, user: root, // 替換為你的用戶名 password: yourpassword, // 替換為你的密碼 database: mcp_demo, waitForConnections: true, connectionLimit: 10, queueLimit: 0 });這里使用連接池而不是單連接是為了避免在高頻調用下出現連接數耗盡的問題。連接參數務必通過環境變量如process.env.DB_HOST管理切勿硬編碼在代碼中。第二步初始化MCP Server并聲明能力// 初始化Server const server new Server( { name: mysql-server, version: 0.1.0, }, { capabilities: { tools: {}, // 我們將在這里注冊工具 resources: {} // 我們將在這里注冊資源 } } ); // 定義工具執行SQL查詢 server.setRequestHandler(tools/list, async () { return { tools: [ { name: execute_query, description: Execute a SELECT SQL query against the MySQL database. Use this for reading data., inputSchema: { type: object, properties: { sql: { type: string, description: The SELECT SQL query to execute. } }, required: [sql] } }, { name: list_tables, description: List all tables in the connected database., inputSchema: { type: object, properties: {} } // 無參數 }, { name: get_table_schema, description: Get the CREATE TABLE statement (schema) for a specific table., inputSchema: { type: object, properties: { tableName: { type: string, description: Name of the table. } }, required: [tableName] } } ] }; });這里我們定義了三個工具。注意execute_query的描述中強調了SELECT這是一種安全實踐避免AI無意中執行DELETE或DROP語句。在生產環境中你需要更嚴格的SQL解析和白名單機制。第三步實現工具調用的處理邏輯這是Server的“肌肉”真正執行操作的地方。// 處理工具調用請求 server.setRequestHandler(tools/call, async (request) { const { name, arguments: args } request.params; try { switch (name) { case execute_query: { const { sql } args; // 簡單的安全校驗只允許SELECT查詢可根據需要放寬 if (!sql.trim().toUpperCase().startsWith(SELECT)) { throw new Error(Only SELECT queries are allowed for safety.); } const [rows] await pool.query(sql); return { content: [ { type: text, text: JSON.stringify(rows, null, 2) // 美化輸出JSON } ] }; } case list_tables: { const [rows] await pool.query(SHOW TABLES); const tableList rows.map(row Object.values(row)[0]).join(\n); return { content: [{ type: text, text: Tables in database:\n${tableList} }] }; } case get_table_schema: { const { tableName } args; const [rows] await pool.query(SHOW CREATE TABLE ${tableName}); const schema rows[0]?.[Create Table]; return { content: [{ type: text, text: schema || Table ${tableName} not found. }] }; } default: throw new Error(Unknown tool: ${name}); } } catch (error) { // 返回結構化的錯誤信息幫助AI和用戶調試 return { content: [{ type: text, text: Error: ${error.message} }], isError: true }; } });關鍵點在于錯誤處理。必須用try...catch包裹并返回格式化的錯誤信息。直接拋出異常可能導致Server進程崩潰破壞整個MCP會話。第四步實現資源讀取可選但推薦為了讓AI更好地“理解”數據庫結構我們提供資源。// 聲明可用的資源 server.setRequestHandler(resources/list, async (request) { const { uri } request.params; // 如果請求了根URI列出所有表資源 if (!uri || uri mysql://schema/) { const [tables] await pool.query(SHOW TABLES); const resources tables.map(table ({ uri: mysql://schema/${Object.values(table)[0]}, name: Schema of table: ${Object.values(table)[0]}, mimeType: text/plain })); // 添加一個總覽資源 resources.unshift({ uri: mysql://schema/, name: Database Schema Overview, mimeType: text/plain }); return { resources }; } return { resources: [] }; }); // 處理資源讀取請求 server.setRequestHandler(resources/read, async (request) { const { uri } request.params; if (uri mysql://schema/) { const [tables] await pool.query(SHOW TABLES); const tableNames tables.map(row - ${Object.values(row)[0]}).join(\n); return { contents: [{ uri, mimeType: text/plain, text: Available tables:\n${tableNames} }] }; } // 匹配表結構URI如 mysql://schema/users const match uri.match(/^mysql:\/\/schema\/(.)$/); if (match) { const tableName match[1]; const [rows] await pool.query(SHOW CREATE TABLE ??, [tableName]); const schema rows[0]?.[Create Table]; return { contents: [{ uri, mimeType: text/plain, text: schema || // Table ${tableName} not found or inaccessible. }] }; } return { contents: [{ uri, mimeType: text/plain, text: // Resource not found: ${uri} }] }; });這里我們設計了一個簡單的資源URI方案mysql://schema/列出所有表mysql://schema/{tableName}獲取具體表結構。這種設計讓AI能按需瀏覽數據庫元數據。第五步啟動Server// 啟動Server使用stdio傳輸 async function main() { const transport new StdioServerTransport(); await server.connect(transport); console.error(MySQL MCP Server running on stdio...); } main().catch((error) { console.error(Server fatal error:, error); process.exit(1); });console.error用于輸出日志因為MCP協議使用stdin/stdout進行通信常規的console.log會干擾協議消息。3.3 本地測試與調試在配置Cursor之前強烈建議先本地測試Server是否正常工作。我們可以寫一個簡單的測試Client腳本test_client.jsconst { Client } require(modelcontextprotocol/sdk/client/index.js); const { StdioClientTransport } require(modelcontextprotocol/sdk/client/stdio.js); const { spawn } require(child_process); async function test() { // 啟動Server進程 const serverProcess spawn(node, [server.js]); const transport new StdioClientTransport(serverProcess); const client new Client( { name: test-client, version: 1.0.0 }, { capabilities: {} } ); await client.connect(transport); // 測試列出工具 const tools await client.listTools(); console.log(Available tools:, tools.tools.map(t t.name)); // 測試列出表 const result await client.callTool({ name: list_tables, arguments: {} }); console.log(List tables result:, result.content[0].text); // 測試查詢 const queryResult await client.callTool({ name: execute_query, arguments: { sql: SELECT * FROM users LIMIT 1 } }); console.log(Query result:, queryResult.content[0].text); await client.close(); serverProcess.kill(); } test().catch(console.error);運行node test_client.js如果看到工具列表和查詢結果恭喜你Server端基本功能已就緒。這個測試步驟能幫你提前發現并解決90%的配置和代碼邏輯問題。4. 在Cursor中集成與配置讓AI助手“上手”Server準備好了現在要讓Cursor這個“大腦”能用上我們造的“手”。Cursor內置了MCP Host支持配置過程直觀。4.1 配置Cursor的MCP設置Cursor的配置主要通過一個JSON文件完成。文件位置通常如下macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json如果目錄或文件不存在手動創建即可。我們需要編輯這個mcp.json文件將我們的MySQL Server添加進去。{ mcpServers: { mysql-local: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/mcp-mysql-server/server.js ], env: { DB_HOST: localhost, DB_USER: root, DB_PASSWORD: yourpassword, DB_DATABASE: mcp_demo } } } }配置詳解與避坑指南絕對路徑是必須的args里的路徑必須是絕對路徑。相對路徑在Cursor的運行時環境中無法正確解析。這是新手最容易踩的坑。在macOS/Linux上可以用pwd命令獲取在Windows上需要完整的盤符路徑。環境變量管理敏感信息永遠不要在配置文件中硬編碼數據庫密碼。通過env字段傳入環境變量然后在server.js中通過process.env.DB_PASSWORD讀取。這樣更安全也便于在不同環境開發、測試間切換。命令與參數command是你系統里可執行命令的名字如node、python3。args是一個數組第一個元素通常是你的腳本文件絕對路徑。如果你的Server是用其他語言如Python、Go寫的這里就需要相應調整。多個ServermcpServers對象可以配置多個Server。比如你還可以同時配置一個用于搜索的tavily-mcpServer。Cursor會自動管理它們。4.2 驗證與使用對話式數據查詢保存mcp.json后完全重啟Cursor。這是關鍵一步因為Cursor只在啟動時讀取這個配置文件。重啟后打開Cursor的聊天界面通常通過Cmd/Ctrl K觸發。如果配置成功你應該能在輸入框下方或模型選擇區域看到類似“可用工具”或“Connected tools”的提示或者至少不會報錯。現在進行一場真正的對話測試你“我們數據庫里有哪些表”Cursor識別到需要查詢數據庫自動調用list_tables工具 “根據查詢數據庫中有以下表users, products, orders。”你“看看users表的結構是什么樣的”Cursor調用get_table_schema工具 “users表的結構如下CREATE TABLE users (id int, name varchar(100), ...)”你“幫我查一下最近創建的5個用戶按時間倒序排列。”Cursor思考后組合已知的表結構和字段生成SQL并調用execute_query “好的查詢語句為SELECT * FROM users ORDER BY created_at DESC LIMIT 5結果如下[...]”這個過程是自動的。Cursor背后的AI模型會根據你的自然語言描述判斷意圖選擇合適的工具并生成正確的調用參數。你不再需要手動編寫或粘貼SQLAI真正成為了你和數據庫之間的“翻譯官”和“操作員”。4.3 高級配置安全性與性能調優基礎配置跑通后為了投入實際使用還需要考慮以下幾點權限最小化在MySQL中為MCP Server創建一個專用用戶只授予它必要的SELECT權限甚至可以通過視圖VIEW來限制其可訪問的數據范圍。絕對不要使用root賬戶。CREATE USER mcp_clientlocalhost IDENTIFIED BY strong_password; GRANT SELECT ON mcp_demo.* TO mcp_clientlocalhost; -- 或者更細粒度 GRANT SELECT ON mcp_demo.public_view TO mcp_clientlocalhost;SQL注入防護我們的簡單示例只做了SELECT前綴檢查這是遠遠不夠的。生產環境中應考慮使用參數化查詢mysql2庫本身支持pool.query(SELECT * FROM users WHERE id ?, [userId])但這對AI動態生成的SQL不直接適用。實現一個簡單的SQL解析器或使用sql-parser等庫進行語法樹白名單校驗只允許無副作用的查詢語句。限制查詢的復雜度如設置最大返回行數LIMIT、禁用多表JOIN或子查詢等。連接池與超時確保MySQL連接池配置合理connectionLimit并在Server端為數據庫查詢設置超時SET SESSION MAX_EXECUTION_TIME10000防止一個慢查詢拖死整個Server。日志與監控在Server中添加詳細的日志記錄工具調用、查詢語句、執行時間、錯誤信息便于后期審計和性能分析。可以將日志輸出到文件或標準錯誤。5. 常見問題、排查與進階思考即使按照步驟操作也難免會遇到問題。這里記錄一些我實踐中遇到的典型情況和解決方法。5.1 問題排查清單問題現象可能原因排查步驟Cursor啟動后無工具提示或聊天中AI不調用工具。1.mcp.json配置文件路徑錯誤或格式錯誤。2. Server啟動失敗如Node路徑錯誤、依賴未安裝。3. Cursor未重啟。1. 檢查mcp.json的JSON語法可用在線校驗工具。2. 在終端手動運行配置中的命令如node /path/to/server.js看是否報錯。3.務必徹底關閉Cursor并重新打開。AI調用了工具但返回“Error”或超時。1. 數據庫連接失敗主機、端口、密碼錯誤。2. SQL語句執行錯誤權限不足、語法錯誤。3. Server代碼邏輯錯誤或未處理異常。1. 使用test_client.js進行本地測試查看具體錯誤信息。2. 檢查Server代碼中的錯誤處理邏輯確保所有await都有try...catch。3. 查看Cursor的開發者控制臺Help - Toggle Developer Tools中的Console日志。工具調用成功但AI不理解結果或胡亂回答。1. 工具返回的數據格式太復雜如嵌套很深的JSON。2. AI的上下文長度有限結果太長被截斷。1. 優化工具返回內容盡量簡潔、結構化。例如將數據庫結果以Markdown表格形式返回比純JSON更易讀。2. 在工具中內置總結或采樣邏輯比如只返回前10行并提供總行數。配置多個Server后AI混淆了工具。不同Server提供的工具名稱或功能相似。在定義工具時使用更具體、包含領域前綴的名稱如mysql_execute_query、postgres_list_tables。在工具描述中也要清晰說明其邊界。5.2 性能優化與擴展方向當基本功能穩定后可以考慮以下優化和擴展讓這個“AI助手”更強大、更智能提供智能提示資源除了基本的表結構可以創建更豐富的Resources。例如mysql://docs/query_examples: 提供一個文檔里面寫一些常用的查詢示例和業務邏輯說明。mysql://stats/table_row_counts: 動態生成一個資源顯示每個表的大致數據量幫助AI決定是否要加LIMIT。這些資源會被AI在思考時自動讀取作為背景知識顯著提升生成SQL的準確性和合理性。實現更復雜的工具不止于查詢可以開發需要邏輯判斷的工具。analyze_query_plan: 接收一個查詢語句返回其EXPLAIN結果讓AI能判斷查詢性能。suggest_index: 基于慢查詢日志或當前查詢模式讓AI給出索引優化建議雖然最終執行需DBA確認。這些工具將AI從“操作員”提升為“初級分析師”。與其他MCP Server聯動MCP的魅力在于組合。你可以同時運行MySQL Server處理數據查詢。文件系統Server讓AI能讀取項目代碼文件。Git Server讓AI能查看提交歷史。Web Search Server如Tavily讓AI能聯網搜索錯誤信息。 這樣你對AI說“根據最近一周的錯誤日志文件去數據庫里查查關聯的用戶訂單MySQL然后看看官方文檔搜索里有沒有解決方案”它就能串聯起多個工具完成一個復雜的工作流。Server實現的多樣性我們的示例是Node.js但MCP協議是語言無關的。社區已經有Python、Go、Rust等多種語言的SDK和示例。你可以根據團隊的技術棧選擇最合適的語言來實現甚至可以封裝現有的腳本或工具為MCP Server極大地降低了集成成本。通過MCP將Cursor與MySQL連接只是一個起點。它展示了一種范式如何將AI大模型強大的語言理解和生成能力與組織內部具體、私有、結構化的工具和數據安全地結合起來。這不僅僅是寫一個插件而是在構建一套讓AI智能體AI Agent真正落地、融入日常研發工作流的基礎設施。當你習慣了用自然語言讓AI幫你查數據、看日志、分析代碼變更時你會發現開發工作的交互方式正在發生靜默但深刻的變革。