|
1 | | -# go-mcp-mysql |
2 | | - |
3 | | -## Overview |
4 | | - |
5 | | -A Model Context Protocol (MCP) server for interacting with MySQL and automation. This server provides tools to list, create, update, and delete MySQL databases and tables. |
6 | | - |
7 | | -Please note that this is a work in progress and may not yet be ready for production use. |
8 | | - |
9 | | -## Roadmap |
10 | | - |
11 | | -- [ ] Implement database listing |
12 | | -- [ ] Implement table listing |
13 | | -- [ ] Implement general CRUD operations |
14 | | -- [ ] Implement read-only mode |
15 | | -- [ ] Implement table creation |
16 | | - |
17 | | -## Tools |
18 | | - |
19 | | -### Schema Tools |
20 | | - |
21 | | -1. `list_database` |
22 | | - |
23 | | - - List all databases in the MySQL server. |
24 | | - - Parameters: None |
25 | | - - Returns: A list of matching database names. |
26 | | - |
27 | | -2. `list_table` |
28 | | - |
29 | | - - List all tables in the MySQL server. |
30 | | - - Parameters: |
31 | | - - `name`: If provided, list tables with the specified name, same as SQL `SHOW TABLES LIKE '%name%'`. Otherwise, list all tables. |
32 | | - - Returns: A list of matching table names. |
33 | | - |
34 | | -3. `create_table` |
35 | | - |
36 | | - - Create a new table in the MySQL server. |
37 | | - - Parameters: |
38 | | - - `query`: The SQL query to create the table. |
39 | | - - Returns: A confirmation message. |
40 | | - |
41 | | -4. `desc_table` |
42 | | - |
43 | | - - Describe the structure of a table. |
44 | | - - Parameters: |
45 | | - - `name`: The name of the table to describe. |
46 | | - - Returns: The structure of the table. |
47 | | - |
48 | | -### Data Tools |
49 | | - |
50 | | -1. `read_query` |
51 | | - |
52 | | - - Execute a read-only SQL query. |
53 | | - - Parameters: |
54 | | - - `query`: The SQL query to execute. |
55 | | - - Returns: The result of the query. |
56 | | - |
57 | | -2. `write_query` |
58 | | - |
59 | | - - Execute a write SQL query. |
60 | | - - Parameters: |
61 | | - - `query`: The SQL query to execute. |
62 | | - - Returns: { affected_rows: number, insert_id: number, last_insert_id: number, rows: number, columns: number, err: string }. |
63 | | - |
64 | | -3. `update_query` |
65 | | - |
66 | | - - Execute an update SQL query. |
67 | | - - Parameters: |
68 | | - - `query`: The SQL query to execute. |
69 | | - - Returns: { affected_rows: number, insert_id: number, last_insert_id: number, rows: number, columns: number, err: string }. |
70 | | - |
71 | | -4. `delete_query` |
72 | | - |
73 | | - - Execute a delete SQL query. |
74 | | - - Parameters: |
75 | | - - `query`: The SQL query to execute. |
76 | | - - Returns: { affected_rows: number, insert_id: number, last_insert_id: number, rows: number, columns: number, err: string }. |
77 | | - |
78 | | -## Installation |
79 | | - |
80 | | -1. Get the latest [release](https://github.com/Zhwt/go-mcp-mysql/releases) and put it in your `$PATH`. |
81 | | - |
82 | | -2. Or if you have Go installed, you can build it from source: |
83 | | - |
84 | | -```sh |
85 | | -go install -v github.com/Zhwt/go-mcp-mysql@latest |
86 | | -``` |
87 | | - |
88 | | -## Usage |
89 | | - |
90 | | -### Method A: Using Command Line Arguments |
91 | | - |
92 | | -```json |
93 | | -{ |
94 | | - "mcpServers": { |
95 | | - "mysql": { |
96 | | - "command": "go-mcp-mysql", |
97 | | - "args": [ |
98 | | - "-h", "localhost", |
99 | | - "-u", "root", |
100 | | - "-p", "password", |
101 | | - "-P", "3306", |
102 | | - "-d", "mydb" |
103 | | - ] |
104 | | - } |
105 | | - } |
106 | | -} |
107 | | -``` |
108 | | - |
109 | | -### Method B: Using DSN With Custom Options |
110 | | - |
111 | | -```json |
112 | | -{ |
113 | | - "mcpServers": { |
114 | | - "mysql": { |
115 | | - "command": "go-mcp-mysql", |
116 | | - "args": [ |
117 | | - "--dsn", "username:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local" |
118 | | - ] |
119 | | - } |
120 | | - } |
121 | | -} |
122 | | -``` |
123 | | - |
124 | | -Please refer to [MySQL DSN](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for more details. |
125 | | - |
126 | | -### Optional Flags |
127 | | - |
128 | | -- Add a `--read-only` flag to enable read-only mode. In this mode, only tools beginning with `list`, `read_` and `desc_` are available. Other tool call will result in an immediate error. |
129 | | - |
130 | | -## License |
131 | | - |
132 | | -MIT |
| 1 | +# go-mcp-mysql |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +Zero burden, ready-to-use Model Context Protocol (MCP) server for interacting with MySQL and automation. No Node.js or Python environment needed. This server provides tools to do CRUD operations on MySQL databases and tables, and a read-only mode to prevent surprise write operations. You can also make the MCP server check the query plan by using a `EXPLAIN` statement before executing the query by adding a `--with-explain-check` flag. |
| 6 | + |
| 7 | +Please note that this is a work in progress and may not yet be ready for production use. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +1. Get the latest [release](https://github.com/Zhwt/go-mcp-mysql/releases) and put it in your `$PATH` or somewhere you can easily access. |
| 12 | + |
| 13 | +2. Or if you have Go installed, you can build it from source: |
| 14 | + |
| 15 | +```sh |
| 16 | +go install -v github.com/Zhwt/go-mcp-mysql@latest |
| 17 | +``` |
| 18 | + |
| 19 | +## Usage |
| 20 | + |
| 21 | +### Method A: Using Command Line Arguments |
| 22 | + |
| 23 | +```json |
| 24 | +{ |
| 25 | + "mcpServers": { |
| 26 | + "mysql": { |
| 27 | + "command": "go-mcp-mysql", |
| 28 | + "args": [ |
| 29 | + "--host", "localhost", |
| 30 | + "--user", "root", |
| 31 | + "--pass", "password", |
| 32 | + "--port", "3306", |
| 33 | + "--db", "mydb" |
| 34 | + ] |
| 35 | + } |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +### Method B: Using DSN With Custom Options |
| 41 | + |
| 42 | +```json |
| 43 | +{ |
| 44 | + "mcpServers": { |
| 45 | + "mysql": { |
| 46 | + "command": "go-mcp-mysql", |
| 47 | + "args": [ |
| 48 | + "--dsn", "username:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local" |
| 49 | + ] |
| 50 | + } |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +Please refer to [MySQL DSN](https://github.com/go-sql-driver/mysql#dsn-data-source-name) for more details. |
| 56 | + |
| 57 | +Note: For those who put the binary outside of your `$PATH`, you need to replace `go-mcp-mysql` with the full path to the binary: e.g.: if you put the binary in the **Downloads** folder, you may use the following path: |
| 58 | + |
| 59 | +```json |
| 60 | +{ |
| 61 | + "mcpServers": { |
| 62 | + "mysql": { |
| 63 | + "command": "C:\\Users\\<username>\\Downloads\\go-mcp-mysql.exe", |
| 64 | + "args": [ |
| 65 | + ... |
| 66 | + ] |
| 67 | + } |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +### Optional Flags |
| 73 | + |
| 74 | +- Add a `--read-only` flag to enable read-only mode. In this mode, only tools beginning with `list`, `read_` and `desc_` are available. Make sure to refresh/restart the MCP server after adding this flag. |
| 75 | +- By default, CRUD queries will be first executed with a `EXPLAIN ?` statement to check whether the generated query plan matches the expected pattern. Add a `--with-explain-check` flag to disable this behavior. |
| 76 | + |
| 77 | +## Tools |
| 78 | + |
| 79 | +### Schema Tools |
| 80 | + |
| 81 | +1. `list_database` |
| 82 | + |
| 83 | + - List all databases in the MySQL server. |
| 84 | + - Parameters: None |
| 85 | + - Returns: A list of matching database names. |
| 86 | + |
| 87 | +2. `list_table` |
| 88 | + |
| 89 | + - List all tables in the MySQL server. |
| 90 | + - Parameters: |
| 91 | + - `name`: If provided, list tables with the specified name, same as SQL `SHOW TABLES LIKE '%name%'`. Otherwise, list all tables. |
| 92 | + - Returns: A list of matching table names. |
| 93 | + |
| 94 | +3. `create_table` |
| 95 | + |
| 96 | + - Create a new table in the MySQL server. |
| 97 | + - Parameters: |
| 98 | + - `query`: The SQL query to create the table. |
| 99 | + - Returns: x rows affected. |
| 100 | + |
| 101 | +4. `alter_table` |
| 102 | + |
| 103 | + - Alter an existing table in the MySQL server. The LLM is informed not to drop an existing table or column. |
| 104 | + - Parameters: |
| 105 | + - `query`: The SQL query to alter the table. |
| 106 | + - Returns: x rows affected. |
| 107 | + |
| 108 | +5. `desc_table` |
| 109 | + |
| 110 | + - Describe the structure of a table. |
| 111 | + - Parameters: |
| 112 | + - `name`: The name of the table to describe. |
| 113 | + - Returns: The structure of the table. |
| 114 | + |
| 115 | +### Data Tools |
| 116 | + |
| 117 | +1. `read_query` |
| 118 | + |
| 119 | + - Execute a read-only SQL query. |
| 120 | + - Parameters: |
| 121 | + - `query`: The SQL query to execute. |
| 122 | + - Returns: The result of the query. |
| 123 | + |
| 124 | +2. `write_query` |
| 125 | + |
| 126 | + - Execute a write SQL query. |
| 127 | + - Parameters: |
| 128 | + - `query`: The SQL query to execute. |
| 129 | + - Returns: x rows affected, last insert id: <last_insert_id>. |
| 130 | + |
| 131 | +3. `update_query` |
| 132 | + |
| 133 | + - Execute an update SQL query. |
| 134 | + - Parameters: |
| 135 | + - `query`: The SQL query to execute. |
| 136 | + - Returns: x rows affected. |
| 137 | + |
| 138 | +4. `delete_query` |
| 139 | + |
| 140 | + - Execute a delete SQL query. |
| 141 | + - Parameters: |
| 142 | + - `query`: The SQL query to execute. |
| 143 | + - Returns: x rows affected. |
| 144 | + |
| 145 | +## License |
| 146 | + |
| 147 | +MIT |
0 commit comments