MCP Server SQLite

Common errors

• ModuleNotFoundError: No module named 'mcp_server_sqlite'

  cause The `mcp-server-sqlite` package is not installed in the current Python environment.
  fix `pip install mcp-server-sqlite`

• AttributeError: module 'mcp_server_sqlite' has no attribute 'MCPSQLiteServer'

  cause Incorrect import path. The `MCPSQLiteServer` class is located within the `server` submodule, not directly under the top-level package.
  fix Change `from mcp_server_sqlite import MCPSQLiteServer` to `from mcp_server_sqlite.server import MCPSQLiteServer`

• sqlite3.OperationalError: database is locked

  cause Another process or application is holding a lock on the SQLite database file, preventing the server from accessing it, or a previous server instance didn't shut down cleanly.
  fix Ensure no other applications are accessing the `.db` file. If a previous server instance crashed, try restarting your application or system to clear any lingering locks. Consider using an absolute path for `database_file` in `MCPSQLiteServer()` to avoid ambiguity and ensure consistent file access.

Warnings

• gotcha The server defaults to creating `mcp_server.db` in the current working directory if no `database_file` is specified during initialization. Running the server from different directories will create separate, distinct database files, leading to data inconsistencies or loss if not explicitly managed.
  Fix: Always specify an absolute or relative path for `database_file` in the `MCPSQLiteServer` constructor, e.g., `MCPSQLiteServer(database_file='path/to/my_server.db')`.
• breaking As `mcp-server-sqlite` heavily relies on the `mcp-server` base library, breaking changes or API shifts in `mcp-server` may indirectly break `mcp-server-sqlite`. The `YYYY.MM.DD` versioning of both projects suggests frequent updates that might not always be backward compatible with older `mcp-server` versions.
  Fix: Always pin both `mcp-server-sqlite` and `mcp-server` to specific versions in your `requirements.txt` to ensure compatibility. Consult the `mcp-server` documentation for its own breaking changes and update both libraries in sync.
• gotcha If the server's `run()` method is not wrapped in a `try...except` block (e.g., `KeyboardInterrupt` or other exceptions), the server will abruptly terminate without graceful shutdown, potentially leaving database connections open or causing data corruption.
  Fix: Wrap the `server.run()` call in a `try...except KeyboardInterrupt` and a general `except Exception` block to handle unexpected shutdowns gracefully, as shown in the quickstart example.

Install

• pip install mcp-server-sqlite Install stable version

Imports

• MCPSQLiteServer
  wrong:

  from mcp_server_sqlite import MCPSQLiteServer

  correct:

  from mcp_server_sqlite.server import MCPSQLiteServer

  The main server class resides in the `server` submodule, not directly in the top-level package.

Quickstart

Initializes and runs a basic MCP server with SQLite persistence. By default, it creates `mcp_server.db` in the current working directory. For robust applications, always specify an absolute database file path and include error handling for graceful shutdown.

import logging
from mcp_server_sqlite.server import MCPSQLiteServer

# Configure basic logging for better visibility
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# Initialize the SQLite MCP server.
# By default, it creates 'mcp_server.db' in the current working directory.
# For production, it's recommended to specify an explicit path:
# server = MCPSQLiteServer(database_file='/var/lib/mcp/my_server.db')
server = MCPSQLiteServer()

print("Starting MCP SQLite server on 0.0.0.0:25565...")
try:
    server.run()
except KeyboardInterrupt:
    logging.info("Server stopped by user (KeyboardInterrupt).")
except Exception as e:
    logging.error(f"An unexpected error occurred: {e}", exc_info=True)