diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a8b9f56
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+# Matrixmc
+
+a matrix<->minecraft bridge for bridging minecraft chat with the matrix protocol, written in golang
+
+## example config
+
+```JSON
+{
+  "logfile": "/minecraft/logs/latest.log",
+  "minecraft": {
+    "address": "localhost:25575",
+    "password": "super-secret-password"
+  },
+  "matrix": {
+    "homeserver": "https://matrix.org",
+    "access_token": "syt__xxxxx",
+    "room": "#gaming:matrix.org",
+    "trusted_users": [
+      "@bob:example.com"
+    ],
+  }
+}
+```
\ No newline at end of file